Document bitfields

This commit is contained in:
Kagami Hiiragi 2015-02-10 19:16:07 +03:00
parent 73a0dc4e56
commit 74bbfda83e

View File

@ -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} * @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 * @constructor
* @static * @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. // NOTE(Kagami): Since pubkey bitfield uses MSB 0, we use it here too.
// See <https://github.com/Bitmessage/PyBitmessage/issues/769> for // See <https://github.com/Bitmessage/PyBitmessage/issues/769> for
// details. // details.
var ServicesBitfield = exports.ServicesBitfield = objectAssign(Bitfield(64), { 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 * @memberof module:bitmessage/structs.ServicesBitfield
* @constant {number} * @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} * @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 * @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), { exports.PubkeyBitfield = objectAssign(Bitfield(32), {
/** /**
* Receiving node expects that the RIPE hash encoded in their address * Returns a boolean indicating whether the bit is set.
* preceedes the encrypted message data of msg messages bound for * @param {number} index - Bit index (MSB 0)
* them. * @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 * @memberof module:bitmessage/structs.PubkeyBitfield
* @constant {number} * @constant {number}
*/ */
INCLUDE_DESTINATION: 30, 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). * dropping them).
* @memberof module:bitmessage/structs.PubkeyBitfield * @memberof module:bitmessage/structs.PubkeyBitfield
* @constant {number} * @constant {number}