Add missing javadocs

lib/hdprivatekey.js

@@ -23,6 +23,14 @@ var BITS_TO_BYTES = 1/8;
 var MAXIMUM_ENTROPY_BITS = 512;
 
 
+/**
+ * Represents an instance of an hierarchically derived private key.
+ *
+ * More info on https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki
+ *
+ * @constructor
+ * @param {string|Buffer|Object} arg
+ */
 function HDPrivateKey(arg) {
   /* jshint maxcomplexity: 10 */
   if (arg instanceof HDPrivateKey) {
@@ -52,6 +60,27 @@ function HDPrivateKey(arg) {
   }
 }
 
+/**
+ * Get a derivated child based on a string or number.
+ *
+ * If the first argument is a string, it's parsed as the full path of
+ * derivation. Valid values for this argument include "m" (which returns the
+ * same private key), "m/0/1/40/2'/1000", where the ' quote means a hardened
+ * derivation.
+ *
+ * If the first argument is a number, the child with that index will be
+ * derived. If the second argument is truthy, the hardened version will be
+ * derived. See the example usage for clarification.
+ *
+ * @example
+ * var parent = new HDPrivateKey('xprv...');
+ * var child_0_1_2h = parent.derive(0).derive(1).derive(2, true);
+ * var copy_of_child_0_1_2h = parent.derive("m/0/1/2'");
+ * assert(child_0_1_2h.xprivkey === copy_of_child_0_1_2h);
+ *
+ * @param {string|number} arg
+ * @param {boolean?} hardened
+ */
 HDPrivateKey.prototype.derive = function(arg, hardened) {
   if (_.isNumber(arg)) {
     return this._deriveWithNumber(arg, hardened);
@@ -220,6 +249,13 @@ HDPrivateKey.prototype._generateRandomly = function(network) {
   return HDPrivateKey.fromSeed(Random.getRandomBuffer(64), network);
 };
 
+/**
+ * Generate a private key from a seed, as described in BIP32
+ *
+ * @param {string|Buffer} hexa
+ * @param {*} network
+ * @return HDPrivateKey
+ */
 HDPrivateKey.fromSeed = function(hexa, network) {
   /* jshint maxcomplexity: 8 */
 
@@ -321,10 +357,35 @@ HDPrivateKey._validateBufferArguments = function(arg) {
   }
 };
 
+/**
+ * Returns the string representation of this private key (a string starting
+ * with "xprv..."
+ *
+ * @return string
+ */
 HDPrivateKey.prototype.toString = function() {
   return this.xprivkey;
 };
 
+/**
+ * Returns a plain object with a representation of this private key.
+ *
+ * Fields include:
+ *  * network: either 'livenet' or 'testnet'
+ *  * depth: a number ranging from 0 to 255
+ *  * fingerPrint: a number ranging from 0 to 2^32-1, taken from the hash of the
+ *        associated public key
+ *  * parentFingerPrint: a number ranging from 0 to 2^32-1, taken from the hash
+ *        of this parent's associated public key or zero.
+ *  * childIndex: the index from which this child was derived (or zero)
+ *  * chainCode: an hexa string representing a number used in the derivation
+ *  * privateKey: the private key associated, in hexa representation
+ *  * xprivkey: the representation of this extended private key in checksum
+ *        base58 format
+ *  * checksum: the base58 checksum of xprivkey
+ *
+ *  @return {Object}
+ */
 HDPrivateKey.prototype.toObject = function() {
   return {
     network: Network.get(bufferUtil.integerFromBuffer(this._buffers.version)).name,
@@ -339,6 +400,12 @@ HDPrivateKey.prototype.toObject = function() {
   };
 };
 
+/**
+ * Returns a string with the results from <tt>toObject</tt>
+ *
+ * @see {HDPrivateKey#toObject}
+ * @return {string}
+ */
 HDPrivateKey.prototype.toJson = function() {
   return JSON.stringify(this.toObject());
 };

lib/hdpublickey.js

@@ -16,7 +16,14 @@ var assert = require('assert');
 var jsUtil = require('./util/js');
 var bufferUtil = require('./util/buffer');
 
-
+/**
+ * The representation of an hierarchically derived public key.
+ *
+ * See https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki
+ *
+ * @constructor
+ * @param {Object|string|Buffer} arg
+ */
 function HDPublicKey(arg) {
   /* jshint maxcomplexity: 12 */
   /* jshint maxstatements: 20 */
@@ -55,6 +62,27 @@ function HDPublicKey(arg) {
   }
 }
 
+/**
+ * Get a derivated child based on a string or number.
+ *
+ * If the first argument is a string, it's parsed as the full path of
+ * derivation. Valid values for this argument include "m" (which returns the
+ * same private key), "m/0/1/40/2/1000".
+ *
+ * Note that hardened keys can't be derived from a public extended key.
+ *
+ * If the first argument is a number, the child with that index will be
+ * derived. See the example usage for clarification.
+ *
+ * @example
+ * var parent = new HDPublicKey('xpub...');
+ * var child_0_1_2 = parent.derive(0).derive(1).derive(2);
+ * var copy_of_child_0_1_2 = parent.derive("m/0/1/2");
+ * assert(child_0_1_2.xprivkey === copy_of_child_0_1_2);
+ *
+ * @param {string|number} arg
+ * @param {boolean?} hardened
+ */
 HDPublicKey.prototype.derive = function (arg, hardened) {
   if (_.isNumber(arg)) {
     return this._deriveWithNumber(arg, hardened);
@@ -298,10 +326,30 @@ HDPublicKey._validateBufferArguments = function (arg) {
   }
 };
 
+/**
+ * Returns the base58 checked representation of the public key
+ * @return {string} a string starting with "xpub..." in livenet
+ */
 HDPublicKey.prototype.toString = function () {
   return this.xpubkey;
 };
 
+/**
+ * Returns a plain javascript object with information to reconstruct a key.
+ *
+ * Fields are:
+ *  * network: 'livenet' or 'testnet'
+ *  * depth: a number from 0 to 255, the depth to the master extended key
+ *  * fingerPrint: a number of 32 bits taken from the hash of the public key
+ *  * fingerPrint: a number of 32 bits taken from the hash of this key's
+ *        parent's public key
+ *  * childIndex: index with which this key was derived
+ *  * chainCode: string in hexa encoding used for derivation
+ *  * publicKey: string, hexa encoded, in compressed key format
+ *  * checksum: bufferUtil.integerFromBuffer(this._buffers.checksum),
+ *  * xpubkey: the string with the base58 representation of this extended key
+ *  * checksum: the base58 checksum of xpubkey
+ */
 HDPublicKey.prototype.toObject = function () {
   return {
     network: Network.get(bufferUtil.integerFromBuffer(this._buffers.version)).name,
@@ -316,6 +364,12 @@ HDPublicKey.prototype.toObject = function () {
   };
 };
 
+/**
+ * Returns the JSON representation of this key's <tt>toObject</tt> result
+ *
+ * @see {HDPublicKey#toObject}
+ * @return {string}
+ */
 HDPublicKey.prototype.toJson = function () {
   return JSON.stringify(this.toObject());
 };