From 74bbfda83e662dd435bff7a5d315ff677bfa47ff Mon Sep 17 00:00:00 2001
From: Kagami Hiiragi <kagami@genshiken.org>
Date: Tue, 10 Feb 2015 19:16:07 +0300
Subject: [PATCH] Document bitfields

---
 lib/structs.js | 71 +++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 62 insertions(+), 9 deletions(-)

diff --git a/lib/structs.js b/lib/structs.js
index 838ad00..ee860e4 100644
--- a/lib/structs.js
+++ b/lib/structs.js
@@ -801,18 +801,42 @@ var Bitfield = function(size) {
 };
 
 /**
- * Services bitfield features.
+ * Service features bitfield (MSB 0).
  * @see {@link https://bitmessage.org/wiki/Protocol_specification#version}
+ * @param {?Buffer} buf - A 8-byte bitfield buffer (will be created if
+ * not provided or will be copied if `opts.copy` is `true`)
+ * @param {?Object} opts - Options
  * @constructor
  * @static
+ * @example
+ * var ServicesBitfield = require("bitmessage").structs.ServicesBitfield;
+ * var services = ServicesBitfield().set(ServicesBitfield.NODE_NETWORK);
+ * console.log(services.get(ServicesBitfield.NODE_NETWORK));  // true
+ * console.log(services.get(15));  // false
  */
-// TODO(Kagami): Document methods.
 // NOTE(Kagami): Since pubkey bitfield uses MSB 0, we use it here too.
 // See <https://github.com/Bitmessage/PyBitmessage/issues/769> for
 // details.
 var ServicesBitfield = exports.ServicesBitfield = objectAssign(Bitfield(64), {
   /**
-   * This is a normal network node.
+   * Returns a boolean indicating whether the bit is set.
+   * @param {number} index - Bit index (MSB 0)
+   * @function get
+   * @instance
+   * @return {boolean}
+   * @memberof module:bitmessage/structs.ServicesBitfield
+   */
+  /**
+   * Set the given bit(s) to `1`.
+   * @param {(number|number[])} index - Bit(s) index (MSB 0)
+   * @function set
+   * @instance
+   * @return {Object} Returns self so methods can be chained.
+   * @memberof module:bitmessage/structs.ServicesBitfield
+   */
+
+  /**
+   * Bit index indicating normal network node.
    * @memberof module:bitmessage/structs.ServicesBitfield
    * @constant {number}
    */
@@ -820,22 +844,51 @@ var ServicesBitfield = exports.ServicesBitfield = objectAssign(Bitfield(64), {
 });
 
 /**
- * Pubkey bitfield features.
+ * Pubkey features bitfield (MSB 0).
  * @see {@link https://bitmessage.org/wiki/Protocol_specification#Pubkey_bitfield_features}
+ * @param {?Buffer} buf - A 4-byte bitfield buffer (will be created if
+ * not provided or will be copied if `opts.copy` is `true`)
+ * @param {?Object} opts - Options
  * @constructor
+ * @example
+ * var PubkeyBitfield = require("bitmessage").structs.PubkeyBitfield;
+ * var behavior = PubkeyBitfield().set([
+ *   PubkeyBitfield.INCLUDE_DESTINATION,
+ *   PubkeyBitfield.DOES_ACK,
+ * ]).set(1);
+ * console.log(behavior.get(PubkeyBitfield.DOES_ACK));  // true
+ * console.log(behavior.get(15));  // false
  */
-// TODO(Kagami): Document methods.
 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.
+   * Returns a boolean indicating whether the bit is set.
+   * @param {number} index - Bit index (MSB 0)
+   * @function get
+   * @instance
+   * @return {boolean}
+   * @memberof module:bitmessage/structs.PubkeyBitfield
+   */
+  /**
+   * Set the given bit(s) to `1`.
+   * @param {(number|number[])} index - Bit(s) index (MSB 0)
+   * @function set
+   * @instance
+   * @return {Object} Returns self so methods can be chained.
+   * @memberof module:bitmessage/structs.PubkeyBitfield
+   */
+
+  /**
+   * Bit index.
+   * If set, the receiving node expects that the RIPEMD 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
+   * Bit index.
+   * If set, the receiving node does send acknowledgements (rather than
    * dropping them).
    * @memberof module:bitmessage/structs.PubkeyBitfield
    * @constant {number}