docs: objects

lib/address.js

@@ -33,7 +33,8 @@ var popkey = require("./_util").popkey;
  * @param {Object=} opts - 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 {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

lib/messages.js

@@ -5,7 +5,6 @@
  * @see {@link https://bitmessage.org/Bitmessage%20Technical%20Paper.pdf}
  * @module bitmessage/messages
  */
-// TODO(Kagami): Document object-like params.
 
 "use strict";
 

lib/objects.js

@@ -1,14 +1,10 @@
 /**
  * Working with objects.  
- * NOTE: Most operations with objects in this module are asynchronous
+ * NOTE: Most operations with objects are asynchronous and return
- * and return promises.
+ * promises.
  * @see {@link https://bitmessage.org/wiki/Protocol_specification#Object_types}
  * @module bitmessage/objects
  */
-// TODO(Kagami): Document object-like params.
-// FIXME(Kagami): Think through the API, we may want to get decoded
-// structure even if it contains unsupported version. Also error
-// handling may need some refactoring.
 
 "use strict";
 
@@ -48,14 +44,7 @@ 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
+ * The same as [getType]{@link module:bitmessage/objects.getType}.
- * 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 {?number} Object's type if any.
  */
 exports.getPayloadType = function(buf) {
   // Object header: 8 + 8 + 4
@@ -101,12 +90,30 @@ function prependNonce(obj, opts) {
  * @static
  */
 var getpubkey = exports.getpubkey = {
+  /**
+   * @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} ripe - The RIPEMD hash of the requested public
+   * keys for address version <= 3
+   * @property {Buffer} tag - ...or tag derived from the address object
+   * for address version >= 4
+   * @property {number} length - Real data length
+   * @memberof module:bitmessage/objects.getpubkey
+   */
+
   /**
    * Decode `getpubkey` object message.
    * @param {Buffer} buf - Message
-   * @param {Object=} opts - Decoding options
+   * @param {Object=} opts - Any of [object.decode]{@link
-   * @return {Promise.<Object>} A promise that contains decoded
+   * module:bitmessage/structs.object.decode} options
-   * `getpubkey` object structure when fulfilled.
+   * @return {Promise.<DecodeResult>} A promise that contains
+   * [decoded `getpubkey` structure]{@link
+   * module:bitmessage/objects.getpubkey.DecodeResult} when fulfilled.
    */
   decodeAsync: function(buf, opts) {
     return new PPromise(function(resolve) {
@@ -118,10 +125,8 @@ var getpubkey = exports.getpubkey = {
 
   /**
    * Decode `getpubkey` object message payload.
-   * @param {Buffer} buf - Message payload
+   * The same as [decodeAsync]{@link
-   * @param {Object=} opts - Decoding options
+   * module:bitmessage/objects.getpubkey.decodeAsync}.
-   * @return {Promise.<Object>} A promise that contains decoded
-   * `getpubkey` object structure when fulfilled.
    */
   decodePayloadAsync: function(buf, opts) {
     return new PPromise(function(resolve) {
@@ -146,6 +151,10 @@ var getpubkey = exports.getpubkey = {
   /**
    * Encode `getpubkey` object message.
    * @param {Object} opts - `getpubkey` object options
+   * @param {number} opts.ttl - Time to live in seconds
+   * @param {Address} opts.to - Receiver of the message
+   * @param {boolean=} opts.skipPow - Do not compute POW (false by
+   * default)
    * @return {Promise.<Buffer>} A promise that contains encoded message
    * when fulfilled.
    */
@@ -157,9 +166,8 @@ var getpubkey = exports.getpubkey = {
 
   /**
    * Encode `getpubkey` object message payload.
-   * @param {Object} opts - `getpubkey` object options
+   * The same as
-   * @return {Promise.<Buffer>} A promise that contains encoded message
+   * [encodeAsync]{@link module:bitmessage/objects.getpubkey.encodeAsync}.
-   * payload when fulfilled.
    */
   encodePayloadAsync: function(opts) {
     return new PPromise(function(resolve) {
@@ -242,12 +250,45 @@ function findAddrByTag(addrs, tag) {
  * @static
  */
 var pubkey = exports.pubkey = {
+  /**
+   * @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} tag - Tag derived from the address object
+   * (present only if object version is 4)
+   * @property {Object} behavior - [Pubkey features]{@link
+   * module:bitmessage/structs.PubkeyBitfield} that can be expected from
+   * the node
+   * @property {Buffer} signPublicKey - Signing public key
+   * @property {Buffer} encPublicKey - Encryption public key
+   * @property {number} nonceTrialsPerByte - Difficulty parameter of the
+   * node (present only for `pubkey` version >= 3)
+   * @property {number} payloadLengthExtraBytes - Difficulty parameter
+   * of the node (present only for `pubkey` version >= 3)
+   * @property {Buffer} signature - Signature of the message (present
+   * only for `pubkey` version >= 3)
+   * @property {number} length - Real data length
+   * @memberof module:bitmessage/objects.pubkey
+   */
+
   /**
    * Decode `pubkey` object message.
    * @param {Buffer} buf - Message
-   * @param {Object=} opts - Decoding options
+   * @param {Object=} opts - Any of [object.decode]{@link
-   * @return {Promise.<Object>} A promise that contains decoded `pubkey`
+   * module:bitmessage/structs.object.decode} options and:
-   * object structure when fulfilled.
+   * @param {(Address[]|Address|Object)} opts.needed - Address objects
+   * which represent pubkeys that we are interested in (used only for
+   * pubkeys v4). It is either addresses array or single address or
+   * Object addr-by-tag. Time to match the key is O(n), O(1), O(1)
+   * respectfully.
+   * @return {Promise.<DecodeResult>} A promise that contains
+   * [decoded `pubkey` structure]{@link
+   * module:bitmessage/objects.pubkey.DecodeResult}
+   * when fulfilled.
    */
   decodeAsync: function(buf, opts) {
     return new PPromise(function(resolve) {
@@ -259,10 +300,8 @@ var pubkey = exports.pubkey = {
 
   /**
    * Decode `pubkey` object message payload.
-   * @param {Buffer} buf - Message payload
+   * The same as [decodeAsync]{@link
-   * @param {Object=} opts - Decoding options
+   * module:bitmessage/objects.pubkey.decodeAsync}.
-   * @return {Promise.<Object>} A promise that contains decoded `pubkey`
-   * object structure when fulfilled.
    */
   decodePayloadAsync: function(buf, opts) {
     return new PPromise(function(resolve) {
@@ -341,6 +380,11 @@ var pubkey = exports.pubkey = {
   /**
    * Encode `pubkey` object message.
    * @param {Object} opts - `pubkey` object options
+   * @param {number} opts.ttl - Time to live in seconds
+   * @param {Address} opts.from - Originator of the message
+   * @param {Address} opts.to - Receiver of the message
+   * @param {boolean=} opts.skipPow - Do not compute POW (false by
+   * default)
    * @return {Promise.<Buffer>} A promise that contains encoded message
    * when fulfilled.
    */
@@ -352,9 +396,8 @@ var pubkey = exports.pubkey = {
 
   /**
    * Encode `pubkey` object message payload.
-   * @param {Object} opts - `pubkey` object options
+   * The same as [encodeAsync]{@link
-   * @return {Promise.<Buffer>} A promise that contains encoded message
+   * module:bitmessage/objects.pubkey.encodeAsync}.
-   * payload when fulfilled.
    */
   encodePayloadAsync: function(opts) {
     return new PPromise(function(resolve) {
@@ -540,12 +583,49 @@ var msg = exports.msg = {
    */
   SIMPLE: 2,
 
+  /**
+   * @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 {number} senderVersion - Sender's address version
+   * @property {number} senderStream - Sender's stream
+   * @property {Object} behavior - Sender's [pubkey features]{@link
+   * module:bitmessage/structs.PubkeyBitfield} that can be expected from
+   * the node
+   * @property {Buffer} signPublicKey - Sender's signing public key
+   * @property {Buffer} encPublicKey - Sender's encryption public key
+   * @property {number} nonceTrialsPerByte - Difficulty parameter of the
+   * sender (present only if sender's address version >= 3)
+   * @property {number} payloadLengthExtraBytes - Difficulty parameter
+   * of the sender (present only if sender's address version >= 3)
+   * @property {Buffer} ripe - The RIPEMD hash of the receiver's keys
+   * @property {number} encoding - Message encoding
+   * @property {(string|Buffer)} message - Message string for
+   * [TRIVIAL]{@link module:bitmessage/objects.msg.TRIVIAL} and
+   * [SIMPLE]{@link module:bitmessage/objects.msg.SIMPLE} encodings or
+   * unparsed buffer data for other encodings
+   * @property {string=} subject - Subject string for [SIMPLE]{@link
+   * module:bitmessage/objects.msg.SIMPLE} encoding
+   * @property {Buffer} ack - Message acknowledgement
+   * @property {Buffer} signature - Signature of the message
+   * @property {number} length - Real data length
+   * @memberof module:bitmessage/objects.msg
+   */
+
   /**
    * Decode `msg` object message.
    * @param {Buffer} buf - Message
-   * @param {Object} opts - Decoding options
+   * @param {Object} opts - Any of [object.decode]{@link
-   * @return {Promise.<Object>} A promise that contains decoded `msg`
+   * module:bitmessage/structs.object.decode} options and:
-   * object structure when fulfilled.
+   * @param {(Address[]|Address)} opts.identities - Address objects used
+   * to decrypt the message
+   * @return {Promise.<DecodeResult>} A promise that contains [decoded
+   * `msg` structure]{@link module:bitmessage/objects.msg.DecodeResult}
+   * when fulfilled.
    */
   decodeAsync: function(buf, opts) {
     return new PPromise(function(resolve) {
@@ -557,10 +637,8 @@ var msg = exports.msg = {
 
   /**
    * Decode `msg` object message payload.
-   * @param {Buffer} buf - Message payload
+   * The same as [decodeAsync]{@link
-   * @param {Object} opts - Decoding options
+   * module:bitmessage/objects.msg.decodeAsync}.
-   * @return {Promise.<Object>} A promise that contains decoded `msg`
-   * object structure when fulfilled.
    */
   decodePayloadAsync: function(buf, opts) {
     return new PPromise(function(resolve) {
@@ -590,7 +668,7 @@ var msg = exports.msg = {
           var rest = decrypted.slice(decoded.length);
 
           // Pow extra.
-          if (decoded.senderVersion >= 3) {
+          if (senderVersion >= 3) {
             var decodedTrials = var_int.decode(rest);
             decoded.nonceTrialsPerByte = decodedTrials.value;
             decoded.length += decodedTrials.length;
@@ -658,6 +736,18 @@ var msg = exports.msg = {
   /**
    * Encode `msg` object message.
    * @param {Object} opts - `msg` object options
+   * @param {number} opts.ttl - Time to live in seconds
+   * @param {Address} opts.from - Originator of the message
+   * @param {Address} opts.to - Receiver of the message
+   * @param {(string|Buffer)} opts.message - Message
+   * @param {(string|Buffer)=} opts.subject - Subject for [SIMPLE]{@link
+   * module:bitmessage/objects.msg.SIMPLE} encoding
+   * @param {number=} opts.encoding - Encoding of the message
+   * ([TRIVIAL]{@link module:bitmessage/objects.msg.TRIVIAL} by default)
+   * @param {boolean=} opts.friend - Whether the receiver is friend and
+   * should have minimal POW difficulty (false by default)
+   * @param {boolean=} opts.skipPow - Do not compute POW (false by
+   * default)
    * @return {Promise.<Buffer>} A promise that contains encoded message
    * when fulfilled.
    */
@@ -669,9 +759,8 @@ var msg = exports.msg = {
 
   /**
    * Encode `msg` object message payload.
-   * @param {Object} opts - `msg` object options
+   * The same as [encodeAsync]{@link
-   * @return {Promise.<Buffer>} A promise that contains encoded message
+   * module:bitmessage/objects.msg.encodeAsync}.
-   * payload when fulfilled.
    */
   encodePayloadAsync: function(opts) {
     return new PPromise(function(resolve) {
@@ -784,12 +873,52 @@ function tryDecryptBroadcastV4(subscriptions, buf) {
  * @static
  */
 var broadcast = exports.broadcast = {
+  /**
+   * @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} tag - Tag derived from the address object used
+   * to send this `broadcast` (present only for object version >= 5)
+   * @property {number} senderVersion - Sender's address version
+   * @property {number} senderStream - Sender's stream
+   * @property {Object} behavior - Sender's [pubkey features]{@link
+   * module:bitmessage/structs.PubkeyBitfield} that can be expected from
+   * the node
+   * @property {Buffer} signPublicKey - Sender's signing public key
+   * @property {Buffer} encPublicKey - Sender's encryption public key
+   * @property {number} nonceTrialsPerByte - Difficulty parameter of the
+   * sender (present only if sender's address version >= 3)
+   * @property {number} payloadLengthExtraBytes - Difficulty parameter
+   * of the sender (present only if sender's address version >= 3)
+   * @property {number} encoding - Message encoding
+   * @property {(string|Buffer)} message - Message string for
+   * [TRIVIAL]{@link module:bitmessage/objects.msg.TRIVIAL} and
+   * [SIMPLE]{@link module:bitmessage/objects.msg.SIMPLE} encodings or
+   * unparsed buffer data for other encodings
+   * @property {string=} subject - Subject string for [SIMPLE]{@link
+   * module:bitmessage/objects.msg.SIMPLE} encoding
+   * @property {Buffer} signature - Signature of the message
+   * @property {number} length - Real data length
+   * @memberof module:bitmessage/objects.broadcast
+   */
+
   /**
    * Decode `broadcast` object message.
    * @param {Buffer} buf - Message
-   * @param {Object} opts - Decoding options
+   * @param {Object} opts - Any of [object.decode]{@link
-   * @return {Promise.<Object>} A promise that contains decoded
+   * module:bitmessage/structs.object.decode} options and:
-   * `broadcast` object structure when fulfilled.
+   * @param {(Address[]|Address|Object)} opts.subscriptions - Address
+   * objects which represent broadcast subscriptions. It is either
+   * addresses array or single address or Object
+   * addr-by-tag/addr-by-ripe. Time to match the key is O(n), O(1), O(1)
+   * respectfully.
+   * @return {Promise.<DecodeResult>} A promise that contains
+   * [decoded `broadcast` structure]{@link
+   * module:bitmessage/objects.broadcast.DecodeResult} when fulfilled.
    */
   decodeAsync: function(buf, opts) {
     return new PPromise(function(resolve) {
@@ -801,10 +930,8 @@ var broadcast = exports.broadcast = {
 
   /**
    * Decode `broadcast` object message payload.
-   * @param {Buffer} buf - Message payload
+   * The same as [decodeAsync]{@link
-   * @param {Object} opts - Decoding options
+   * module:bitmessage/objects.broadcast.decodeAsync}.
-   * @return {Promise.<Object>} A promise that contains decoded `pubkey`
-   * object structure when fulfilled.
    */
   decodePayloadAsync: function(buf, opts) {
     return new PPromise(function(resolve) {
@@ -931,6 +1058,15 @@ var broadcast = exports.broadcast = {
   /**
    * Encode `broadcast` object message.
    * @param {Object} opts - `broadcast` object options
+   * @param {number} opts.ttl - Time to live in seconds
+   * @param {Address} opts.from - Originator of the message
+   * @param {(string|Buffer)} opts.message - Message
+   * @param {(string|Buffer)=} opts.subject - Subject for [SIMPLE]{@link
+   * module:bitmessage/objects.msg.SIMPLE} encoding
+   * @param {number=} opts.encoding - Encoding of the message
+   * ([TRIVIAL]{@link module:bitmessage/objects.msg.TRIVIAL} by default)
+   * @param {boolean=} opts.skipPow - Do not compute POW (false by
+   * default)
    * @return {Promise.<Buffer>} A promise that contains encoded message
    * when fulfilled.
    */
@@ -942,9 +1078,8 @@ var broadcast = exports.broadcast = {
 
   /**
    * Encode `broadcast` object message payload.
-   * @param {Object} opts - `broadcast` object options
+   * The same as [encodeAsync]{@link
-   * @return {Promise.<Buffer>} A promise that contains encoded message
+   * module:bitmessage/objects.broadcast.encodeAsync}.
-   * payload when fulfilled.
    */
   encodePayloadAsync: function(opts) {
     return new PPromise(function(resolve) {

lib/wif.js

@@ -17,7 +17,8 @@ function getwifchecksum(data) {
 }
 
 /**
- * Decode WIF encoded private key.
+ * Decode WIF-encoded private key (corresponded to a uncompressed public
+ * key).
  * @param {string} wif - Encoded key
  * @return {Buffer} Private key.
  */
@@ -31,9 +32,10 @@ exports.decode = function(wif) {
 };
 
 /**
- * Convert private key to a WIF.
+ * Convert private key to a WIF (corresponded to a uncompressed public
+ * key).
  * @param {Buffer} privateKey - A private key to encode
- * @return {string} Encoded private key.
+ * @return {string} WIF-encoded private key.
  */
 exports.encode = function(privateKey) {
   var data = Buffer.concat([new Buffer([0x80]), privateKey]);