Added comments.

src/util.js

@@ -38,10 +38,19 @@ for (var i = 0; i < names.length; ++i)
 
 // Bitcoin utility functions
 Bitcoin.Util = {
-  isArray: Array.isArray || function(o) {
+  /**
+   * Cross-browser compatibility version of Array.isArray.
+   */
+  isArray: Array.isArray || function(o)
+  {
     return Object.prototype.toString.call(o) === '[object Array]';
   },
-  makeFilledArray: function (len, val) {
+
+  /**
+   * Create an array of a certain length filled with a specific value.
+   */
+  makeFilledArray: function (len, val)
+  {
     var array = [];
     var i = 0;
     while (i < len) {
@@ -49,8 +58,16 @@ Bitcoin.Util = {
     }
     return array;
   },
-  numToVarInt: function (i) {
-    // TODO: THIS IS TOTALLY UNTESTED!
+
+  /**
+   * Turn an integer into a "var_int".
+   *
+   * "var_int" is a variable length integer used by Bitcoin's binary format.
+   *
+   * Returns a byte array.
+   */
+  numToVarInt: function (i)
+  {
     if (i < 0xfd) {
       // unsigned char
       return [i];
@@ -65,12 +82,30 @@ Bitcoin.Util = {
       return [0xff].concat(Crypto.util.wordsToBytes([i >>> 32, i]));
     }
   },
-  valueToBigInt: function (valueBuffer) {
+
+  /**
+   * Parse a Bitcoin value byte array, returning a BigInteger.
+   */
+  valueToBigInt: function (valueBuffer)
+  {
     if (valueBuffer instanceof BigInteger) return valueBuffer;
 
     // Prepend zero byte to prevent interpretation as negative integer
     return BigInteger.fromByteArrayUnsigned(valueBuffer);
   },
+
+  /**
+   * Format a Bitcoin value as a string.
+   *
+   * Takes a BigInteger or byte-array and returns that amount of Bitcoins in a
+   * nice standard formatting.
+   *
+   * Examples:
+   * 12.3555
+   * 0.1234
+   * 900.99998888
+   * 34.00
+   */
   formatValue: function (valueBuffer) {
     var value = this.valueToBigInt(valueBuffer).toString();
     var integerPart = value.length > 8 ? value.substr(0, value.length-8) : '0';
@@ -80,7 +115,16 @@ Bitcoin.Util = {
     while (decimalPart.length < 2) decimalPart += "0";
     return integerPart+"."+decimalPart;
   },
+
+  /**
+   * Parse a floating point string as a Bitcoin value.
+   *
+   * Keep in mind that parsing user input is messy. You should always display
+   * the parsed value back to the user to make sure we understood his input
+   * correctly.
+   */
   parseValue: function (valueString) {
+    // TODO: Detect other number formats (e.g. comma as decimal separator)
     var valueComp = valueString.split('.');
     var integralPart = valueComp[0];
     var fractionalPart = valueComp[1] || "0";
@@ -91,6 +135,13 @@ Bitcoin.Util = {
     value = value.add(BigInteger.valueOf(parseInt(fractionalPart)));
     return value;
   },
+
+  /**
+   * Calculate RIPEMD160(SHA256(data)).
+   *
+   * Takes an arbitrary byte array as inputs and returns the hash as a byte
+   * array.
+   */
   sha256ripe160: function (data) {
     return Crypto.RIPEMD160(Crypto.SHA256(data, {asBytes: true}), {asBytes: true});
   }