From 9f368d32fba523553a416d1a10990221690c2723 Mon Sep 17 00:00:00 2001
From: Kagami Hiiragi <kagami@genshiken.org>
Date: Sat, 31 Jan 2015 14:51:35 +0300
Subject: [PATCH] Improve documentation

---
 lib/address.js    | 20 ++++++++++--------
 lib/crypto.js     | 11 ++++++----
 lib/index.js      |  7 +++++--
 lib/messages.js   | 53 ++++++++++++++++++++++++++++++++++++++---------
 lib/objects.js    | 40 +++++++++++++++--------------------
 lib/pow.js        |  3 ++-
 lib/structs.js    | 51 ++++++++++++++++++++++++++++++---------------
 lib/user-agent.js | 16 +++++++++-----
 package.json      |  2 +-
 9 files changed, 131 insertions(+), 72 deletions(-)

diff --git a/lib/address.js b/lib/address.js
index 0a827b0..1229836 100644
--- a/lib/address.js
+++ b/lib/address.js
@@ -47,9 +47,9 @@ Address.prototype.clone = function() {
 };
 
 /**
- * Test if given object is an Address instance. NOTE: Implementation is
- * just simple `instanceof` but it improves readability and consistent
- * with `isArray`, `isBuffer`, etc.
+ * Test if 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
  * @return {boolean}
  */
@@ -59,7 +59,7 @@ Address.isAddress = function(obj) {
 
 /**
  * Parse Bitmessage address into address object.
- * @param {String} str - Address string (with or without `BM-` prefix)
+ * @param {string} str - Address string (with or without `BM-` prefix)
  * @return {Address} Decoded address object.
  */
 Address.decode = function(str) {
@@ -116,8 +116,8 @@ function getaddrhash(addr) {
 }
 
 /**
- * Calculate the encryption key used to encrypt/decrypt {@link pubkey}
- * objects.
+ * Calculate the encryption key used to encrypt/decrypt
+ * [pubkey]{@link module:bitmessage/objects.pubkey} objects.
  * @return {Buffer} A 32-byte private key.
  */
 Address.prototype.getPubkeyPrivateKey = function() {
@@ -126,7 +126,8 @@ Address.prototype.getPubkeyPrivateKey = function() {
 
 /**
  * Calculate the corresponding public key for encryption key used to
- * encrypt/decrypt {@link pubkey} objects.
+ * encrypt/decrypt
+ * [pubkey]{@link module:bitmessage/objects.pubkey} objects.
  * @return {Buffer} A 65-byte public key.
  */
 Address.prototype.getPubkeyPublicKey = function() {
@@ -135,7 +136,7 @@ Address.prototype.getPubkeyPublicKey = function() {
 
 /**
  * Calculate the encryption key used to encrypt/decrypt
- * {@link broadcast} objects.
+ * [broadcast]{@link module:bitmessage/objects.broadcast} objects.
  * @return {Buffer} A 32-byte private key.
  */
 Address.prototype.getBroadcastPrivateKey = function() {
@@ -148,7 +149,8 @@ Address.prototype.getBroadcastPrivateKey = function() {
 
 /**
  * Calculate the corresponding public key for encryption key used to
- * encrypt/decrypt {@link broadcast} objects.
+ * encrypt/decrypt
+ * [broadcast]{@link module:bitmessage/objects.broadcast} objects.
  * @return {Buffer} A 65-byte public key.
  */
 Address.prototype.getBroadcastPublicKey = function() {
diff --git a/lib/crypto.js b/lib/crypto.js
index 654a145..f78d3e5 100644
--- a/lib/crypto.js
+++ b/lib/crypto.js
@@ -1,6 +1,6 @@
 /**
  * Isomorphic Bitmessage crypto module. Reexports platform-dependent
- * implementations and and also some common routines.
+ * implementations and also some common routines.
  * @module bitmessage/crypto
  */
 
@@ -72,7 +72,7 @@ exports.getPublic = eccrypto.getPublic;
 /**
  * Sign message using ecdsa-with-sha1 scheme.
  * @param {Buffer} privateKey - A 32-byte private key
- * @msg {Buffer} msg - The message being signed
+ * @param {Buffer} msg - The message being signed
  * @return {Promise.<Buffer>} A promise that contains signature in DER
  * format when fulfilled.
  */
@@ -84,7 +84,7 @@ exports.sign = function(privateKey, msg) {
 /**
  * Verify signature using ecdsa-with-sha1 scheme.
  * @param {Buffer} publicKey - A 65-byte public key
- * @msg {Buffer} msg - The message being verified
+ * @param {Buffer} msg - The message being verified
  * @param {Buffer} sig - The signature in DER format
  * @return {Promise.<undefined>} A promise that resolves on correct
  * signature and rejects on bad key or signature.
@@ -152,6 +152,9 @@ var encrypted = exports.encrypted = {
  * @return {Promise.<Buffer>} - A promise that resolves with the buffer
  * in `encrypted` format successful encryption and rejects on failure.
  */
+// TODO(Kagami): Properly document `opts`. Documenting multiple
+// function arguments with options object at the end for now gives
+// strange results (probably a bug in jsdoc).
 exports.encrypt = function(publicKeyTo, msg, opts) {
   return eccrypto.encrypt(publicKeyTo, msg, opts).then(function(encObj) {
     return encrypted.encode(encObj);
@@ -162,7 +165,7 @@ exports.encrypt = function(publicKeyTo, msg, opts) {
  * Decrypt message using given private key.
  * @param {Buffer} privateKey - A 32-byte private key of recepient of
  * the mesage
- * @param {Buffer} buf - encrypted data
+ * @param {Buffer} buf - Encrypted data
  * @return {Promise.<Buffer>} - A promise that resolves with the
  * plaintext on successful decryption and rejects on failure.
  */
diff --git a/lib/index.js b/lib/index.js
index 03c72f1..1f11ba3 100644
--- a/lib/index.js
+++ b/lib/index.js
@@ -5,7 +5,10 @@
 
 "use strict";
 
-/** Current protocol version. */
+/**
+ * Current protocol version.
+ * @constant {number}
+ */
 exports.PROTOCOL_VERSION = require("./_util").PROTOCOL_VERSION;
 
 /** [Common structures.]{@link module:bitmessage/structs} */
@@ -22,5 +25,5 @@ exports.POW = require("./pow");
 
 /** [Working with addresses.]{@link module:bitmessage/address} */
 exports.Address = require("./address");
-/** [User Agent.]{@link module:bitmessage/user-agent} */
+/** [User agent.]{@link module:bitmessage/user-agent} */
 exports.UserAgent = require("./user-agent");
diff --git a/lib/messages.js b/lib/messages.js
index 8b72082..6c95e35 100644
--- a/lib/messages.js
+++ b/lib/messages.js
@@ -21,11 +21,12 @@ var ServicesBitfield = structs.ServicesBitfield;
 /**
  * Try to get command of the given encoded message.
  * Note that this function doesn't do any validation because it is
- * already provided by `message.decode` routine. Normally you call this
- * for each incoming message and then call decode function of the
- * appropriate message handler.
+ * already provided by
+ * [message.decode]{@link module:bitmessage/structs.message.decode}
+ * routine. Normally you call this for each incoming message and then
+ * call decode function of the appropriate message handler.
  * @param {Buffer} buf - Buffer that starts with encoded message
- * @return {?string} Message's command if any
+ * @return {?string} Message's command if any.
  */
 exports.getCommand = function(buf) {
   if (buf.length < 16) {
@@ -49,7 +50,10 @@ exports.getCommand = function(buf) {
  * @static
  */
 var version = exports.version = {
-  /** Random nonce used to detect connections to self. */
+  /**
+   * Random nonce used to detect connections to self.
+   * @const {Buffer}
+   */
   NONCE: new Buffer("20bde0a3355dad78", "hex"),
 
   /**
@@ -260,7 +264,7 @@ var inv = exports.inv = {
 
   /**
    * Encode `inv` message.
-   * @param {Buffer[]} inventory - Inventory vector list (encoded)
+   * @param {Buffer[]} inventory - Inventory vector list
    * @return {Buffer} Encoded message.
    */
   encode: function(inventory) {
@@ -270,7 +274,7 @@ var inv = exports.inv = {
 
   /**
    * Encode `inv` message payload.
-   * @param {Buffer[]} inventory - Inventory vector list (encoded)
+   * @param {Buffer[]} inventory - Inventory vector list
    * @return {Buffer} Encoded payload.
    */
   encodePayload: function(inventory) {
@@ -281,22 +285,48 @@ var inv = exports.inv = {
 };
 
 /**
- * `getdata` message. `getdata` is used in response to an `inv` message
- * to retrieve the content of a specific object after filtering known
- * elements.
+ * `getdata` message. `getdata` is used in response to an
+ * [inv]{@link module:bitmessage/messages.inv} message to retrieve the
+ * content of a specific object after filtering known elements.
  * @see {@link https://bitmessage.org/wiki/Protocol_specification#getdata}
  * @namespace
  */
 exports.getdata = objectAssign({}, inv, {
+  /**
+   * Decode `getdata` message.
+   * @param {Buffer} buf - Message
+   * @return {Object} Decoded `getdata` structure.
+   * @memberof module:bitmessage/messages.getdata
+   */
   decode: function(buf) {
     var decoded = message.decode(buf);
     assert(decoded.command === "getdata", "Bad command");
     return inv.decodePayload(decoded.payload);
   },
+  /**
+   * Encode `getdata` message.
+   * @param {Buffer[]} inventory - Inventory vector list
+   * @return {Buffer} Encoded message.
+   * @memberof module:bitmessage/messages.getdata
+   */
   encode: function(inventory) {
     var payload = inv.encodePayload(inventory);
     return message.encode("getdata", payload);
   },
+  /**
+   * Decode `getdata` message payload.
+   * @param {Buffer} buf - Message payload
+   * @return {Object} Decoded `inv` structure.
+   * @function decodePayload
+   * @memberof module:bitmessage/messages.getdata
+   */
+  /**
+   * Encode `getdata` message payload.
+   * @param {Buffer[]} inventory - Inventory vector list
+   * @return {Buffer} Encoded payload.
+   * @function encodePayload
+   * @memberof module:bitmessage/messages.getdata
+   */
 });
 
 /**
@@ -308,17 +338,20 @@ exports.getdata = objectAssign({}, inv, {
 var error = exports.error = {
   /**
    * Just a warning.
+   * @constant {number}
    */
   WARNING: 0,
 
   /**
    * It's an error, something was going wrong (e.g. an object got lost).
+   * @constant {number}
    */
   ERROR: 1,
 
   /**
    * It's a fatal error. The node will drop the line for that error and
    * maybe ban you for some time.
+   * @constant {number}
    */
   FATAL: 2,
 
diff --git a/lib/objects.js b/lib/objects.js
index 08030f0..63e1e7c 100644
--- a/lib/objects.js
+++ b/lib/objects.js
@@ -1,5 +1,5 @@
 /**
- * Working with objects.
+ * Working with objects.  
  * NOTE: Most operations with objects in this module are asynchronous
  * and return promises.
  * @see {@link https://bitmessage.org/wiki/Protocol_specification#Object_types}
@@ -30,11 +30,12 @@ var object = structs.object;
 /**
  * Try to get type of the given encoded object message.
  * Note that this function doesn't do any validation because it is
- * already provided by `object.decode` routine. Normally you call this
- * for each incoming object message and then call decode function of the
- * appropriate object handler.
+ * already provided by
+ * [object.decode]{@link module:bitmessage/structs.object.decode}
+ * routine. Normally you call this for each incoming object message and
+ * then call decode function of the appropriate object handler.
  * @param {Buffer} buf - Buffer that starts with encoded object message
- * @return {?integer} Object's type if any
+ * @return {?number} Object's type if any.
  */
 exports.getType = function(buf) {
   // Message header: 4 + 12 + 4 + 4
@@ -48,11 +49,13 @@ exports.getType = function(buf) {
 /**
  * Try to get type of the given object message payload.
  * Note that this function doesn't do any validation because it is
- * already provided by `object.decodePayload` routine. Normally you call
- * this for each incoming object message payload and then call decode
- * function of the appropriate object handler.
+ * already provided by
+ * [object.decodePayload]{@link module:bitmessage/structs.object.decodePayload}
+ * routine. Normally you call this for each incoming object message
+ * payload and then call decode function of the appropriate object
+ * handler.
  * @param {Buffer} buf - Buffer that starts with object message payload
- * @return {?integer} Object's type if any
+ * @return {?number} Object's type if any.
  */
 exports.getPayloadType = function(buf) {
   // Object header: 8 + 8 + 4
@@ -258,11 +261,6 @@ var pubkey = exports.pubkey = {
    * Decode `pubkey` object message payload.
    * @param {Buffer} buf - Message payload
    * @param {?Object} opts - Decoding options
-   * @param {?(Address[]|Address|Object)} opts.needed - Address objects
-   * which represent pubkeys that we are interested in. This is used
-   * only for pubkeys v4. `needed` is either single address or addresses
-   * array or Object addr-by-tag. Time to match the key is O(1), O(n),
-   * O(1) respectfully.
    * @return {Promise.<Object>} A promise that contains decoded `pubkey`
    * object structure when fulfilled.
    */
@@ -526,22 +524,25 @@ var msg = exports.msg = {
   /**
    * Any data with this number may be ignored. The sending node might
    * simply be sharing its public key with you.
+   * @constant {number}
    */
   IGNORE: 0,
   /**
    * UTF-8. No 'Subject' or 'Body' sections. Useful for simple strings
    * of data, like URIs or magnet links.
+   * @constant {number}
    */
   TRIVIAL: 1,
   /**
    * UTF-8. Uses 'Subject' and 'Body' sections. No MIME is used.
+   * @constant {number}
    */
   SIMPLE: 2,
 
   /**
    * Decode `msg` object message.
    * @param {Buffer} buf - Message
-   * @param {?Object} opts - Decoding options
+   * @param {Object} opts - Decoding options
    * @return {Promise.<Object>} A promise that contains decoded `msg`
    * object structure when fulfilled.
    */
@@ -557,8 +558,6 @@ var msg = exports.msg = {
    * Decode `msg` object message payload.
    * @param {Buffer} buf - Message payload
    * @param {Object} opts - Decoding options
-   * @param {(Address[]|Address)} opts.identities - Address objects used
-   * to decrypt the message
    * @return {Promise.<Object>} A promise that contains decoded `msg`
    * object structure when fulfilled.
    */
@@ -786,7 +785,7 @@ var broadcast = exports.broadcast = {
   /**
    * Decode `broadcast` object message.
    * @param {Buffer} buf - Message
-   * @param {?Object} opts - Decoding options
+   * @param {Object} opts - Decoding options
    * @return {Promise.<Object>} A promise that contains decoded
    * `broadcast` object structure when fulfilled.
    */
@@ -802,11 +801,6 @@ var broadcast = exports.broadcast = {
    * Decode `broadcast` object message payload.
    * @param {Buffer} buf - Message payload
    * @param {Object} opts - Decoding options
-   * @param {(Address[]|Address|Object)} opts.subscriptions - Address
-   * objects which represent broadcast subscriptions. `subscriptions` is
-   * either single address or addresses array or Object
-   * addr-by-tag/addr-by-ripe. Time to match the key is O(1), O(n), O(1)
-   * respectfully.
    * @return {Promise.<Object>} A promise that contains decoded `pubkey`
    * object structure when fulfilled.
    */
diff --git a/lib/pow.js b/lib/pow.js
index c41e623..fdd7676 100644
--- a/lib/pow.js
+++ b/lib/pow.js
@@ -13,9 +13,10 @@ var platform = require("./platform");
 var util = require("./_util");
 
 /**
- * Calculate target
+ * Calculate target.
  * @param {Object} opts - Target options
  * @return {number} Target.
+ * @function
  * @static
  */
 // Just a wrapper around platform-specific implementation.
diff --git a/lib/structs.js b/lib/structs.js
index 54a8c48..a743745 100644
--- a/lib/structs.js
+++ b/lib/structs.js
@@ -35,11 +35,14 @@ function getmsgchecksum(data) {
  * @static
  */
 var message = exports.message = {
-  /** Bitmessage magic value. */
+  /**
+   * Bitmessage magic value.
+   * @constant {number}
+   */
   MAGIC: 0xE9BEB4D9,
 
   /**
-   * Decode message structure.
+   * Decode message structure.  
    * NOTE: `payload` is copied, `rest` references input buffer.
    * @param {Buffer} buf - Buffer that starts with encoded message
    * @return {{command: string, payload: Buffer, length: number, rest: Buffer}}
@@ -95,9 +98,9 @@ var message = exports.message = {
 };
 
 /**
- * `object` message. An `object` is a message which is shared throughout
- * a stream. It is the only message which propagates; all others are
- * only between two nodes.
+ * An `object` is a message which is shared throughout a stream. It is
+ * the only message which propagates; all others are only between two
+ * nodes.
  * @see {@link https://bitmessage.org/wiki/Protocol_specification#object}
  * @namespace
  * @static
@@ -110,7 +113,7 @@ var object = exports.object = {
   BROADCAST: 3,
 
   /**
-   * Decode `object` message.
+   * Decode `object` message.  
    * NOTE: `nonce` and `objectPayload` are copied.
    * @param {Buffer} buf - Message
    * @param {?Object} opts - Decoding options
@@ -123,7 +126,7 @@ var object = exports.object = {
   },
 
   /**
-   * Decode `object` message payload.
+   * Decode `object` message payload.  
    * NOTE: `nonce` and `objectPayload` are copied.
    * @param {Buffer} buf - Message payload
    * @param {?Object} opts - Decoding options
@@ -238,7 +241,7 @@ var object = exports.object = {
  */
 var var_int = exports.var_int = {
   /**
-   * Decode `var_int`.
+   * Decode `var_int`.  
    * NOTE: `rest` references input buffer.
    * @param {Buffer} buf - A buffer that starts with encoded `var_int`
    * @return {{value: number, length: number, rest: Buffer}}
@@ -331,7 +334,7 @@ var var_int = exports.var_int = {
  */
 exports.var_str = {
   /**
-   * Decode `var_str`.
+   * Decode `var_str`.  
    * NOTE: `rest` references input buffer.
    * @param {Buffer} buf - A buffer that starts with encoded `var_str`
    * @return {{str: string, length: number, rest: Buffer}}
@@ -367,7 +370,7 @@ exports.var_str = {
  */
 exports.var_int_list = {
   /**
-   * Decode `var_int_list`.
+   * Decode `var_int_list`.  
    * NOTE: `rest` references input buffer.
    * @param {Buffer} buf - A buffer that starts with encoded
    * `var_int_list`
@@ -496,7 +499,9 @@ exports.net_addr = {
   /**
    * Decode `net_addr`.
    * @param {Buffer} buf - A buffer that contains encoded `net_addr`
-   * @param {?Object} opts - Decode options
+   * @param {?Object} opts - Decoding options; use `short` option to
+   * decode `net_addr` from
+   * [version message]{@link module:bitmessage/messages.version}
    * @return {Object} Decoded `net_addr` structure.
    */
   decode: function(buf, opts) {
@@ -526,7 +531,8 @@ exports.net_addr = {
   /**
    * Encode `net_addr`.
    * @param {Object} opts - Encode options; use `short` option to encode
-   * `net_addr` used in version message
+   * `net_addr` for
+   * [version message]{@link module:bitmessage/messages.version}
    * @return {Buffer} Encoded `net_addr`.
    */
   encode: function(opts) {
@@ -565,7 +571,7 @@ exports.net_addr = {
 exports.inv_vect = {
   /**
    * Encode inventory vector.
-   * @param {Buffer} buf - Payload to calculate inventory vector for
+   * @param {Buffer} buf - Payload to calculate the inventory vector for
    * @return {Buffer} Encoded `inv_vect`.
    */
   encode: function(buf) {
@@ -577,19 +583,22 @@ exports.inv_vect = {
  * Encrypted payload.
  * @see {@link https://bitmessage.org/wiki/Protocol_specification#Encrypted_payload}
  * @namespace encrypted
+ * @static
  */
 /**
- * Decode encrypted payload.
+ * Decode encrypted payload.  
  * NOTE: all structure members are copied.
  * @param {Buffer} buf - A buffer that contains encrypted payload
  * @return {Object} Decoded encrypted structure.
- * @function encrypted.decode
+ * @function decode
+ * @memberof module:bitmessage/structs.encrypted
  */
 /**
  * Encode `encrypted`.
  * @param {Object} opts - Encode options
  * @return {Buffer} Encoded encrypted payload.
- * @function encrypted.encode
+ * @function encode
+ * @memberof module:bitmessage/structs.encrypted
  */
 // Reexport struct.
 exports.encrypted = bmcrypto.encrypted;
@@ -662,7 +671,11 @@ var Bitfield = function(size) {
 // See <https://github.com/Bitmessage/PyBitmessage/issues/769> for
 // details.
 var ServicesBitfield = exports.ServicesBitfield = objectAssign(Bitfield(64), {
-  /** This is a normal network node. */
+  /**
+   * This is a normal network node.
+   * @memberof module:bitmessage/structs.ServicesBitfield
+   * @constant {number}
+   */
   NODE_NETWORK: 63,
 });
 
@@ -677,11 +690,15 @@ exports.PubkeyBitfield = objectAssign(Bitfield(32), {
    * Receiving node expects that the RIPE hash encoded in their address
    * preceedes the encrypted message data of msg messages bound for
    * them.
+   * @memberof module:bitmessage/structs.PubkeyBitfield
+   * @constant {number}
    */
   INCLUDE_DESTINATION: 30,
   /**
    * If true, the receiving node does send acknowledgements (rather than
    * dropping them).
+   * @memberof module:bitmessage/structs.PubkeyBitfield
+   * @constant {number}
    */
   DOES_ACK: 31,
 });
diff --git a/lib/user-agent.js b/lib/user-agent.js
index eac04ab..594c120 100644
--- a/lib/user-agent.js
+++ b/lib/user-agent.js
@@ -10,19 +10,23 @@ var var_str = require("./structs").var_str;
 var BM_NAME = require("../package.json").name;
 var BM_VERSION = require("../package.json").version;
 
-/** User agent of the bitmessage library itself. */
+/**
+ * User agent of the bitmessage library itself.
+ * @constant {Object[]}
+ * @static
+ */
 var SELF = exports.SELF = [{name: BM_NAME, version: BM_VERSION}];
 
 /**
- * Decode user agent `var_str`. Just an alias for
- * {@link var_str.decode}
+ * Decode user agent's `var_str`. Just an alias for
+ * [var_str.decode]{@link module:bitmessage/structs.var_str.decode}.
  * @function
  */
 exports.decode = var_str.decode;
 
 /**
  * Parse raw user agent into software stack list. Most underlying
- * software comes first.
+ * software comes first.  
  * NOTE: Decoding is rather loose, it won't fail on bad user agent
  * format because it's not that important.
  * @param {string} str - Raw user agent string
@@ -59,8 +63,10 @@ exports.parse = function(str) {
  * Encode user agent into `var_str` Buffer. Most underlying software
  * comes first.
  * @param {(Object[]|string[]|string)} software - List of software to
- * encode or raw user agent string
+ * encode or just raw user agent string
  * @return {Buffer} Encoded user agent.
+ * @function
+ * @static
  */
 var encode = exports.encode = function(software) {
   var ua;
diff --git a/package.json b/package.json
index ca07ce3..3412ae8 100644
--- a/package.json
+++ b/package.json
@@ -35,7 +35,7 @@
   "homepage": "https://github.com/bitchan/bitmessage",
   "devDependencies": {
     "chai": "*",
-    "jsdoc": "^3.3.0-alpha13",
+    "jsdoc": "^3.3.0-beta1",
     "jshint": "*",
     "karma": "^0.12.31",
     "karma-browserify": "^2.0.0",