Document address module

This commit is contained in:
Kagami Hiiragi 2015-02-10 16:40:57 +03:00
parent 2ae5d40463
commit 68c7966bef
2 changed files with 45 additions and 13 deletions

View File

@ -1,8 +1,21 @@
/**
* Working with Bitmessage addresses.
* **NOTE**: `Address` is exported as a module.
* @example
* var Address = require("bitmessage").Address;
* // Or: var Address = require("bitmessage/address");
*
* // Generate a new random Bitmessage identity.
* var addr1 = Address.fromRandom();
* console.log("New random Bitmessage address:", addr1.encode());
*
* // Or create it from passphrase.
* var addr2 = Address.fromPassphrase("test");
* console.log("Deterministic Bitmessage address:", addr2.encode());
* @see {@link https://bitmessage.org/wiki/Address}
* @module bitmessage/address
*/
// TODO(Kagami): Document getters/setters.
"use strict";
@ -17,7 +30,15 @@ var popkey = require("./_util").popkey;
/**
* Create a new Bitmessage address object.
* @param {?Object} opts - Address options
* @param {?Object} opts - Optional 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 {Buffer} opts.signPrivateKey - Signing private key
* @param {Buffer} opts.signPublicKey - Signing public key
* @param {Buffer} opts.encPrivateKey - Encryption private key
* @param {Buffer} opts.encPublicKey - Encryption public key
* @param {Buffer} opts.ripe - Keys RIPEMD hash
* @constructor
* @static
*/
@ -47,7 +68,7 @@ Address.prototype.clone = function() {
};
/**
* Test if given object is an Address instance.
* Test if the 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
@ -98,8 +119,8 @@ function getaddrchecksum(data) {
}
/**
* Get the ripe hash of the address without prefix zeroes.
* @return {Buffer} A short ripe hash.
* Get the RIPEMD hash of the address keys without prefix nulls.
* @return {Buffer} A short RIPEMD hash.
*/
Address.prototype.getShortRipe = function() {
var ripe = this.ripe;
@ -225,10 +246,15 @@ Address.prototype.encode = function() {
};
/**
* Create new Bitmessage address from random encryption and signing
* Create a new Bitmessage address with random encryption and signing
* private keys.
* @param {?Object} opts - Address options
* @return {Address} Generated address object.
* @param {?Object} opts - Optional address options
* @param {number} opts.ripeLength - Required length of the short RIPEMD
* hash (19 by default)
* @param {number} opts.version - Version number
* @param {number} opts.stream - Stream number
* @param {Object} opts.behavior - [Pubkey features]{@link module:bitmessage/structs.PubkeyBitfield}
* @return {Address} New address object.
*/
Address.fromRandom = function(opts) {
opts = objectAssign({}, opts);
@ -258,9 +284,15 @@ Address.fromRandom = function(opts) {
};
/**
* Create new Bitmessage address from passphrase.
* @param {?Object} opts - Address options
* @return {Address} Generated address object.
* Create a new Bitmessage address from passphrase.
* @param {(string|Object)} opts - Passphrase or address options
* @param {string} opts.passphrase - Passphrase to generate address from
* @param {?number} opts.ripeLength - Required length of the short
* RIPEMD hash (19 by default)
* @param {?number} opts.version - Version number
* @param {?number} opts.stream - Stream number
* @param {?Object} opts.behavior - [Pubkey features]{@link module:bitmessage/structs.PubkeyBitfield}
* @return {Address} New address object.
*/
Address.fromPassphrase = function(opts) {
if (typeof opts === "string") {

View File

@ -803,7 +803,7 @@ var Bitfield = function(size) {
/**
* Services bitfield features.
* @see {@link https://bitmessage.org/wiki/Protocol_specification#version}
* @namespace
* @constructor
* @static
*/
// TODO(Kagami): Document methods.
@ -822,7 +822,7 @@ var ServicesBitfield = exports.ServicesBitfield = objectAssign(Bitfield(64), {
/**
* Pubkey bitfield features.
* @see {@link https://bitmessage.org/wiki/Protocol_specification#Pubkey_bitfield_features}
* @namespace
* @constructor
*/
// TODO(Kagami): Document methods.
exports.PubkeyBitfield = objectAssign(Bitfield(32), {