docs: structs

lib/structs.js

@@ -3,7 +3,6 @@
  * @see {@link https://bitmessage.org/wiki/Protocol_specification#Common_structures}
  * @module bitmessage/structs
  */
-// TODO(Kagami): Document object-like params.
 
 "use strict";
 
@@ -83,13 +82,25 @@ var message = exports.message = {
    */
   MAGIC: 0xE9BEB4D9,
 
+  /**
+   * @typedef {Object} TryDecodeResult
+   * @property {Object} message - Decoded message
+   * @property {string} message.command - Message command
+   * @property {Buffer} message.payload - Message payload
+   * @property {number} message.length - Full message length
+   * @property {Error} error - ...or decoding error
+   * @property {Buffer} rest - The rest of the input buffer after
+   * processing message
+   * @memberof module:bitmessage/structs.message
+   */
+
   /**
    * Decode message in "stream" mode.  
    * NOTE: message payload and `rest` are copied (so the runtime can GC
    * processed buffer data).
    * @param {Buffer} buf - Data buffer
-   * @return {?{?message: Object, ?error: Error, rest: Buffer}} Decoded
+   * @return {?TryDecodeResult}
-   * result.
+   * [Decoded result.]{@link module:bitmessage/structs.message.TryDecodeResult}
    */
   tryDecode: function(buf) {
     if (buf.length < 24) {
@@ -169,12 +180,21 @@ var message = exports.message = {
     return res;
   },
 
+  /**
+   * @typedef {Object} DecodeResult
+   * @property {string} command - Message command
+   * @property {Buffer} payload - Message payload
+   * @property {number} length - Full message length
+   * @property {Buffer} rest - The rest of the input buffer
+   * @memberof module:bitmessage/structs.message
+   */
+
   /**
    * 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}}
+   * @return {DecodeResult}
-   * Decoded message structure.
+   * [Decoded message structure.]{@link module:bitmessage/structs.message.DecodeResult}
    */
   decode: function(buf) {
     assert(buf.length >= 24, "Buffer is too small");
@@ -237,18 +257,48 @@ var message = exports.message = {
  * @static
  */
 var object = exports.object = {
-  // Known types.
+  /**
+   * [getpubkey]{@link module:bitmessage/objects.getpubkey} object type.
+   * @constant {number}
+   */
   GETPUBKEY: 0,
+  /**
+   * [pubkey]{@link module:bitmessage/objects.pubkey} object type.
+   * @constant {number}
+   */
   PUBKEY: 1,
+  /**
+   * [msg]{@link module:bitmessage/objects.msg} object type.
+   * @constant {number}
+   */
   MSG: 2,
+  /**
+   * [broadcast]{@link module:bitmessage/objects.broadcast} object type.
+   * @constant {number}
+   */
   BROADCAST: 3,
 
+  /**
+   * @typedef {Object} DecodeResult
+   * @property {Buffer} nonce - A 8-byte object nonce
+   * @property {number} ttl - Time to live in seconds
+   * @property {number} type - Object type
+   * @property {number} version - Object version
+   * @property {number} stream - Object stream
+   * @property {number} headerLength - Length of the object header
+   * @property {Buffer} objectPayload - Object payload
+   * @memberof module:bitmessage/structs.object
+   */
+
   /**
    * Decode `object` message.  
    * NOTE: `nonce` and `objectPayload` are copied.
    * @param {Buffer} buf - Message
    * @param {Object=} opts - Decoding options
-   * @return {Object} Decoded `object` structure.
+   * @param {boolean} opts.allowExpired - Allow expired objects
+   * @param {boolean} opts.skipPow - Do not validate object POW
+   * @return {DecodeResult}
+   * [Decoded `object` structure.]{@link module:bitmessage/structs.object.DecodeResult}
    */
   decode: function(buf, opts) {
     var decoded = message.decode(buf);
@@ -257,11 +307,8 @@ var object = exports.object = {
   },
 
   /**
-   * Decode `object` message payload.  
+   * Decode `object` message payload.
-   * NOTE: `nonce` and `objectPayload` are copied.
+   * The same as [decode]{@link module:bitmessage/structs.object.decode}.
-   * @param {Buffer} buf - Message payload
-   * @param {Object=} opts - Decoding options
-   * @return {Object} Decoded `object` structure.
    */
   decodePayload: function(buf, opts) {
     opts = opts || {};
@@ -309,6 +356,12 @@ var object = exports.object = {
   /**
    * Encode `object` message.
    * @param {Object} opts - Object options
+   * @param {Object} opts.nonce - A 8-byte object nonce
+   * @param {number} opts.ttl - Time to live in seconds
+   * @param {number} opts.type - Object type
+   * @param {number} opts.version - Object version
+   * @param {number=} opts.stream - Object stream (1 by default)
+   * @param {Buffer} opts.objectPayload - Object payload
    * @return {Buffer} Encoded message.
    */
   encode: function(opts) {
@@ -318,8 +371,7 @@ var object = exports.object = {
 
   /**
    * Encode `object` message payload.
-   * @param {Object} opts - Object options
+   * The same as [encode]{@link module:bitmessage/structs.object.encode}.
-   * @return {Buffer} Encoded payload.
    */
   encodePayload: function(opts) {
     // NOTE(Kagami): We do not try to calculate nonce here if it is not
@@ -343,6 +395,11 @@ var object = exports.object = {
    * Encode `object` message payload without leading nonce field (may be
    * useful if you are going to calculate it later).
    * @param {Object} opts - Object options
+   * @param {number} opts.ttl - Time to live in seconds
+   * @param {number} opts.type - Object type
+   * @param {number} opts.version - Object version
+   * @param {number=} opts.stream - Object stream (1 by default)
+   * @param {Buffer} opts.objectPayload - Object payload
    * @return {Buffer} Encoded payload.
    */
   encodePayloadWithoutNonce: function(opts) {
@@ -371,12 +428,20 @@ var object = exports.object = {
  * @static
  */
 var var_int = exports.var_int = {
+  /**
+   * @typedef {Object} DecodeResult
+   * @property {number} value - Stored value
+   * @property {number} length - `var_int` full length
+   * @property {Buffer} rest - The rest of the input buffer
+   * @memberof module:bitmessage/structs.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}}
+   * @return {DecodeResult}
-   * Decoded `var_int` structure.
+   * [Decoded `var_int` structure.]{@link module:bitmessage/structs.var_int.DecodeResult}
    */
   decode: function(buf) {
     var value, length;
@@ -464,12 +529,20 @@ var var_int = exports.var_int = {
  * @namespace
  */
 exports.var_str = {
+  /**
+   * @typedef {Object} DecodeResult
+   * @property {number} str - The string itself
+   * @property {number} length - `var_str` full length
+   * @property {Buffer} rest - The rest of the input buffer
+   * @memberof module:bitmessage/structs.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}}
+   * @return {DecodeResult}
-   * Decoded `var_str` structure.
+   * [Decoded `var_str` structure.]{@link module:bitmessage/structs.var_str.DecodeResult}
    */
   decode: function(buf) {
     var decoded = var_int.decode(buf);
@@ -500,13 +573,21 @@ exports.var_str = {
  * @namespace
  */
 exports.var_int_list = {
+  /**
+   * @typedef {Object} DecodeResult
+   * @property {number} list - Stored numbers
+   * @property {number} length - `var_int_list` full length
+   * @property {Buffer} rest - The rest of the input buffer
+   * @memberof module:bitmessage/structs.var_int_list
+   */
+
   /**
    * Decode `var_int_list`.  
    * NOTE: `rest` references input buffer.
    * @param {Buffer} buf - A buffer that starts with encoded
    * `var_int_list`
-   * @return {{list: number[], length: number, rest: Buffer}}
+   * @return {DecodeResult}
-   * Decoded `var_int_list` structure.
+   * [Decoded `var_int_list` structure.]{@link module:bitmessage/structs.var_int_list.DecodeResult}
    */
   decode: function(buf) {
     var decoded = var_int.decode(buf);
@@ -636,13 +717,28 @@ function inet_pton(str) {
  * @namespace
  */
 exports.net_addr = {
+  /**
+   * @typedef {Object} DecodeResult
+   * @property {Date} time - Time the node was last active, not included
+   * in short mode
+   * @property {number} stream - Stream number of the node, not included
+   * in short mode
+   * @property {Object} services -
+   * [Services]{@link module:bitmessage/structs.ServicesBitfield}
+   * provided by the node
+   * @property {string} host - IPv4/IPv6 address of the node
+   * @property {number} port - Incoming port of the node
+   * @memberof module:bitmessage/structs.net_addr
+   */
+
   /**
    * Decode `net_addr`.
    * @param {Buffer} buf - A buffer that contains encoded `net_addr`
    * @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.
+   * @return {DecodeResult}
+   * [Decoded `net_addr` structure.]{@link module:bitmessage/structs.net_addr.DecodeResult}
    */
   decode: function(buf, opts) {
     var short = !!(opts || {}).short;
@@ -670,9 +766,19 @@ exports.net_addr = {
 
   /**
    * Encode `net_addr`.
-   * @param {Object} opts - Encode options; use `short` option to encode
+   * @param {Object} opts - Encoding options
-   * `net_addr` for
+   * @param {boolean=} opts.short - Encode `net_addr` for
    * [version message]{@link module:bitmessage/messages.version}
+   * (false by default)
+   * @param {Date=} opts.time - Time the node was last active, not
+   * included in short mode (current time by default)
+   * @param {number=} opts.stream - Stream number of the node, not
+   * included in short mode (1 by default)
+   * @param {Object=} opts.services -
+   * [Services]{@link module:bitmessage/structs.ServicesBitfield}
+   * provided by the node (`NODE_NETWORK` by default)
+   * @param {string} opts.host - IPv4/IPv6 address of the node
+   * @param {number} opts.port - Incoming port of the node
    * @return {Buffer} Encoded `net_addr`.
    */
   encode: function(opts) {
@@ -707,8 +813,10 @@ exports.net_addr = {
  * @see {@link https://bitmessage.org/wiki/Protocol_specification#Inventory_Vectors}
  * @namespace
  */
-// Only encode operation is defined because decode is impossible.
 exports.inv_vect = {
+  // NOTE(Kagami): Only encode operation is defined because decoding of
+  // the encoded vector is impossible.
+
   /**
    * Encode inventory vector.
    * @param {Buffer} buf - Payload to calculate the inventory vector for
@@ -725,18 +833,34 @@ exports.inv_vect = {
  * @namespace encrypted
  * @static
  */
+/**
+ * @typedef {Object} DecodeResult
+ * @property {Buffer} iv - Initialization vector (16 bytes)
+ * @property {Buffer} ephemPrivateKey - Ephemeral private key (32 bytes)
+ * @property {Buffer} ciphertext - The result of encryption (variable
+ * size)
+ * @property {Buffer} mac - Message authentication code (32 bytes)
+ * @memberof module:bitmessage/structs.encrypted
+ */
 /**
  * Decode encrypted payload.  
  * NOTE: all structure members are copied.
  * @param {Buffer} buf - A buffer that contains encrypted payload
- * @return {Object} Decoded encrypted structure.
+ * @return {DecodeResult}
+ * [Decoded `encrypted` structure.]{@link module:bitmessage/structs.encrypted.DecodeResult}
  * @function decode
  * @memberof module:bitmessage/structs.encrypted
  */
 /**
  * Encode `encrypted`.
- * @param {Object} opts - Encode options
+ * @param {Object} opts - Encoding options
- * @return {Buffer} Encoded encrypted payload.
+ * @param {Buffer} opts.iv - Initialization vector (16 bytes)
+ * @param {Buffer} opts.ephemPrivateKey - Ephemeral private key (32
+ * bytes)
+ * @param {Buffer} opts.ciphertext - The result of encryption (variable
+ * size)
+ * @param {Buffer} opts.mac - Message authentication code (32 bytes)
+ * @return {Buffer} Encoded `encrypted` payload.
  * @function encode
  * @memberof module:bitmessage/structs.encrypted
  */
@@ -834,6 +958,13 @@ var ServicesBitfield = exports.ServicesBitfield = objectAssign(Bitfield(64), {
    * @return {Object} Returns self so methods can be chained.
    * @memberof module:bitmessage/structs.ServicesBitfield
    */
+  /**
+   * The contents of the bitfield.
+   * @type {Buffer}
+   * @var buffer
+   * @instance
+   * @memberof module:bitmessage/structs.ServicesBitfield
+   */
 
   /**
    * Bit index indicating normal network node.
@@ -876,6 +1007,13 @@ exports.PubkeyBitfield = objectAssign(Bitfield(32), {
    * @return {Object} Returns self so methods can be chained.
    * @memberof module:bitmessage/structs.PubkeyBitfield
    */
+  /**
+   * The contents of the bitfield.
+   * @type {Buffer}
+   * @var buffer
+   * @instance
+   * @memberof module:bitmessage/structs.PubkeyBitfield
+   */
 
   /**
    * Bit index.