From 68c7966befdbac95611c2ff58118558702e39d42 Mon Sep 17 00:00:00 2001
From: Kagami Hiiragi <kagami@genshiken.org>
Date: Tue, 10 Feb 2015 16:40:57 +0300
Subject: [PATCH] Document address module

---
 lib/address.js | 54 ++++++++++++++++++++++++++++++++++++++++----------
 lib/structs.js |  4 ++--
 2 files changed, 45 insertions(+), 13 deletions(-)

diff --git a/lib/address.js b/lib/address.js
index 1229836..cc50dd1 100644
--- a/lib/address.js
+++ b/lib/address.js
@@ -1,8 +1,21 @@
 /**
- * Working with Bitmessage addresses.
+ * Working with Bitmessage addresses.  
+ * **NOTE**: `Address` is exported as a module.
+ * @example
+ * var Address = require("bitmessage").Address;
+ * // Or: var Address = require("bitmessage/address");
+ *
+ * // Generate a new random Bitmessage identity.
+ * var addr1 = Address.fromRandom();
+ * console.log("New random Bitmessage address:", addr1.encode());
+ *
+ * // Or create it from passphrase.
+ * var addr2 = Address.fromPassphrase("test");
+ * console.log("Deterministic Bitmessage address:", addr2.encode());
  * @see {@link https://bitmessage.org/wiki/Address}
  * @module bitmessage/address
  */
+// TODO(Kagami): Document getters/setters.
 
 "use strict";
 
@@ -17,7 +30,15 @@ var popkey = require("./_util").popkey;
 
 /**
  * Create a new Bitmessage address object.
- * @param {?Object} opts - Address options
+ * @param {?Object} opts - Optional address options
+ * @param {number} opts.version - Version number (4 by default)
+ * @param {number} opts.stream - Stream number (1 by default)
+ * @param {Object} opts.behavior - [Pubkey features]{@link module:bitmessage/structs.PubkeyBitfield} (`DOES_ACK` by default)
+ * @param {Buffer} opts.signPrivateKey - Signing private key
+ * @param {Buffer} opts.signPublicKey - Signing public key
+ * @param {Buffer} opts.encPrivateKey - Encryption private key
+ * @param {Buffer} opts.encPublicKey - Encryption public key
+ * @param {Buffer} opts.ripe - Keys RIPEMD hash
  * @constructor
  * @static
  */
@@ -47,7 +68,7 @@ Address.prototype.clone = function() {
 };
 
 /**
- * Test if given object is an Address instance.  
+ * Test if the given object is an Address instance.  
  * NOTE: Implementation is just simple `instanceof` but it improves
  * readability and consistent with `isArray`, `isBuffer`, etc.
  * @param {Object} obj - Given object
@@ -98,8 +119,8 @@ function getaddrchecksum(data) {
 }
 
 /**
- * Get the ripe hash of the address without prefix zeroes.
- * @return {Buffer} A short ripe hash.
+ * Get the RIPEMD hash of the address keys without prefix nulls.
+ * @return {Buffer} A short RIPEMD hash.
  */
 Address.prototype.getShortRipe = function() {
   var ripe = this.ripe;
@@ -225,10 +246,15 @@ Address.prototype.encode = function() {
 };
 
 /**
- * Create new Bitmessage address from random encryption and signing
+ * Create a new Bitmessage address with random encryption and signing
  * private keys.
- * @param {?Object} opts - Address options
- * @return {Address} Generated address object.
+ * @param {?Object} opts - Optional address options
+ * @param {number} opts.ripeLength - Required length of the short RIPEMD
+ * hash (19 by default)
+ * @param {number} opts.version - Version number
+ * @param {number} opts.stream - Stream number
+ * @param {Object} opts.behavior - [Pubkey features]{@link module:bitmessage/structs.PubkeyBitfield}
+ * @return {Address} New address object.
  */
 Address.fromRandom = function(opts) {
   opts = objectAssign({}, opts);
@@ -258,9 +284,15 @@ Address.fromRandom = function(opts) {
 };
 
 /**
- * Create new Bitmessage address from passphrase.
- * @param {?Object} opts - Address options
- * @return {Address} Generated address object.
+ * Create a new Bitmessage address from passphrase.
+ * @param {(string|Object)} opts - Passphrase or address options
+ * @param {string} opts.passphrase - Passphrase to generate address from
+ * @param {?number} opts.ripeLength - Required length of the short
+ * RIPEMD hash (19 by default)
+ * @param {?number} opts.version - Version number
+ * @param {?number} opts.stream - Stream number
+ * @param {?Object} opts.behavior - [Pubkey features]{@link module:bitmessage/structs.PubkeyBitfield}
+ * @return {Address} New address object.
  */
 Address.fromPassphrase = function(opts) {
   if (typeof opts === "string") {
diff --git a/lib/structs.js b/lib/structs.js
index 8462a1e..838ad00 100644
--- a/lib/structs.js
+++ b/lib/structs.js
@@ -803,7 +803,7 @@ var Bitfield = function(size) {
 /**
  * Services bitfield features.
  * @see {@link https://bitmessage.org/wiki/Protocol_specification#version}
- * @namespace
+ * @constructor
  * @static
  */
 // TODO(Kagami): Document methods.
@@ -822,7 +822,7 @@ var ServicesBitfield = exports.ServicesBitfield = objectAssign(Bitfield(64), {
 /**
  * Pubkey bitfield features.
  * @see {@link https://bitmessage.org/wiki/Protocol_specification#Pubkey_bitfield_features}
- * @namespace
+ * @constructor
  */
 // TODO(Kagami): Document methods.
 exports.PubkeyBitfield = objectAssign(Bitfield(32), {