Merge pull request #586 from braydonf/docs/jsdoc-misc-fixes

JSDoc: Update Address, PublicKey and PrivateKey

lib/address.js

@@ -5,20 +5,30 @@ var networks = require('./networks');
 var Hash = require('./crypto/hash');
 
 /**
- *
- * Bitcore Address
  *
  * Instantiate an address from an address String or Buffer, a public key or script hash Buffer,
  * or an instance of PublicKey or Script.
  *
  * @example
  *
- * var address = new Address(keypair.pubkey, 'testnet').toString();
+ * // validate that an input field is valid
+ * var error = Address.getValidationError(input, 'testnet');
+ * if (!error) {
+ *   var address = Address(input, 'testnet');
+ * } else {
+ *   // invalid network or checksum (typo?)
+ *   var message = error.messsage;
+ * }
+ *
+ * // get an address from a public key
+ * var address = Address(publicKey, 'testnet').toString();
+ * 
  *
  * @param {String} data - The encoded data in various formats
  * @param {String} [network] - The network: 'mainnet' or 'testnet'
  * @param {String} [type] - The type of address: 'script' or 'pubkey'
  * @returns {Address} A new valid and frozen instance of an Address
+ * @constructor
  */
 function Address(data, network, type) {
 
@@ -74,6 +84,7 @@ function Address(data, network, type) {
  *
  * @param {Buffer} hash - An instance of a hash Buffer
  * @returns {Object} An object with keys: hashBuffer
+ * @private
  */
 Address._transformHash = function(hash){
   var info = {};
@@ -95,6 +106,7 @@ Address._transformHash = function(hash){
  * @param {String} [network] - The network: 'mainnet' or 'testnet'
  * @param {String} [type] - The type: 'pubkeyhash' or 'scripthash'
  * @returns {Object} An object with keys: hashBuffer, network and type
+ * @private
  */
 Address._transformBuffer = function(buffer, network, type){
   var info = {};
@@ -150,6 +162,7 @@ Address._transformBuffer = function(buffer, network, type){
  *
  * @param {PublicKey} pubkey - An instance of PublicKey
  * @returns {Object} An object with keys: hashBuffer, type
+ * @private
  */
 Address._transformPublicKey = function(pubkey){
   var info = {};
@@ -167,6 +180,7 @@ Address._transformPublicKey = function(pubkey){
  *
  * @param {Script} script - An instance of Script
  * @returns {Object} An object with keys: hashBuffer, type
+ * @private
  */
 Address._transformScript = function(script){
   var info = {};
@@ -186,6 +200,7 @@ Address._transformScript = function(script){
  * @param {String} [network] - The network: 'mainnet' or 'testnet'
  * @param {String} [type] - The type: 'pubkeyhash' or 'scripthash'
  * @returns {Object} An object with keys: hashBuffer, network and type
+ * @private
  */
 Address._transformString = function(data, network, type){
   if( typeof(data) !== 'string' ) {
@@ -348,6 +363,6 @@ Address.prototype.toString = function() {
  */
 Address.prototype.inspect = function() {
   return '<Address: ' + this.toString() + ', type: '+this.type+', network: '+this.network+'>';
-}
+};
 
 module.exports = Address;

lib/privatekey.js

@@ -9,19 +9,28 @@ var Address = require('./address');
 var PublicKey = require('./publickey');
 
 /**
- *
- * Bitcore PrivateKey
  *
  * Instantiate a PrivateKey from a BN, Buffer and WIF.
  *
  * @example
  *
- * var privateKey = new PrivateKey();
+ * // generate a new random key
+ * var key = PrivateKey();
  *
+ * // get the associated address
+ * var address = key.toAddress();
+ *
+ * // encode into wallet export format 
+ * var exported = key.toWIF(); 
+ * 
+ * // instantiate from the exported (and saved) private key
+ * var imported = PrivateKey.fromWIF(exported);
+ * 
  * @param {String} data - The encoded data in various formats
  * @param {String} [network] - Either "mainnet" or "testnet"
  * @param {Boolean} [compressed] - If the key is in compressed format
  * @returns {PrivateKey} A new valid instance of an PrivateKey
+ * @constructor
  */
 var PrivateKey = function PrivateKey(data, network, compressed) {
 
@@ -71,6 +80,7 @@ var PrivateKey = function PrivateKey(data, network, compressed) {
  * Internal function to get a random BN
  *
  * @returns {Object} An object with keys: bn, network and compressed
+ * @private
  */
 PrivateKey._getRandomBN = function(){
   var condition;
@@ -91,6 +101,7 @@ PrivateKey._getRandomBN = function(){
  * @param {String} [network] - Either "mainnet" or "testnet"
  * @param {String} [compressed] - If the private key is compressed
  * @returns {Object} An object with keys: bn, network and compressed
+ * @private
  */
 PrivateKey._transformBuffer = function(buf, network, compressed) {
 
@@ -132,6 +143,7 @@ PrivateKey._transformBuffer = function(buf, network, compressed) {
  *
  * @param {String} buf - An WIF string 
  * @returns {Object} An object with keys: bn, network and compressed
+ * @private
  */
 PrivateKey._transformWIF = function(str, network, compressed) {
   return PrivateKey._transformBuffer(base58check.decode(str), network, compressed);

lib/publickey.js

@@ -4,18 +4,24 @@ var Point = require('./crypto/point');
 var BN = require('./crypto/bn');
 
 /**
- *
- * Bitcore PublicKey
  *
  * Instantiate a PublicKey from a 'PrivateKey', 'Point', 'string', 'Buffer'.
  *
  * @example
  *
- * var publicKey = new PublicKey(privkey, true);
+ * // instantiate from a private key
+ * var key = PublicKey(privateKey, true);
+ * 
+ * // export to as a DER hex encoded string 
+ * var exported = key.toString();
+ * 
+ * // import the public key
+ * var imported = PublicKey.fromString(exported);
  *
  * @param {String} data - The encoded data in various formats
  * @param {String} [compressed] - If the public key is compressed
  * @returns {PublicKey} A new valid instance of an PublicKey
+ * @constructor
  */
 var PublicKey = function PublicKey(data, compressed) {
 
@@ -69,6 +75,7 @@ var PublicKey = function PublicKey(data, compressed) {
  *
  * @param {PrivateKey} privkey - An instance of PrivateKey
  * @returns {Object} An object with keys: point and compressed
+ * @private
  */
 PublicKey._transformPrivateKey = function(privkey) {
   var info = {};
@@ -87,6 +94,7 @@ PublicKey._transformPrivateKey = function(privkey) {
  *
  * @param {Buffer} buf - An hex encoded buffer
  * @returns {Object} An object with keys: point and compressed
+ * @private
  */
 PublicKey._transformDER = function(buf){
   var info = {};
@@ -132,6 +140,7 @@ PublicKey._transformDER = function(buf){
  * @param {Boolean} odd - If the point is above or below the x axis
  * @param {Point} x - The x point
  * @returns {Object} An object with keys: point and compressed
+ * @private
  */
 PublicKey._transformX = function(odd, x){
   var info = {};