Document pow module

This commit is contained in:
Kagami Hiiragi 2015-02-10 21:07:08 +03:00
parent 74bbfda83e
commit 3389359ce5

View File

@ -3,7 +3,6 @@
* @see {@link https://bitmessage.org/wiki/Proof_of_work}
* @module bitmessage/pow
*/
// TODO(Kagami): Find a way how to document object params properly.
"use strict";
@ -15,6 +14,18 @@ var util = require("./_util");
/**
* Calculate target.
* @param {Object} opts - Target options
* @param {number} opts.ttl - Time to live of the message in seconds
* @param {number} opts.payloadLength - Length of the message payload
* (with nonce)
* @param {Buffer} opts.payload - ...or payload itself
* @param {number=} opts.nonceTrialsPerByte - This number is the average
* number of nonce trials a node will have to perform to meet the Proof
* of Work requirement. 1000 is the network minimum so any lower values
* will be automatically raised to 1000.
* @param {number=} opts.payloadLengthExtraBytes - This number is added
* to the data length to make sending small messages more difficult.
* 1000 is the network minimum so any lower values will be automatically
* raised to 1000.
* @return {number} Target.
* @function
* @static
@ -33,6 +44,12 @@ var getTarget = exports.getTarget = function(opts) {
/**
* Check a POW.
* @param {Object} opts - Proof of work options
* @param {number} opts.target - Proof of work target or pass
* [getTarget]{@link module:bitmessage/pow.getTarget} options to `opts`
* to compute it
* @param {Buffer} opts.payload - Message payload (with nonce)
* @param {(number|Buffer)} opts.nonce - ...or already derived nonce
* @param {Buffer} opts.initialHash - ...and initial hash
* @return {boolean} Is the proof of work sufficient.
*/
exports.check = function(opts) {
@ -75,10 +92,13 @@ exports.check = function(opts) {
/**
* Do a POW.
* @param {Object} opts - Proof of work options
* @param {?Buffer} opts.data - Object message payload without nonce to
* @param {Buffer} opts.data - Object message payload without nonce to
* get the initial hash from
* @param {?Buffer} opts.initialHash - Or already computed initial hash
* @param {Buffer} opts.initialHash - ...or already computed initial
* hash
* @param {number} opts.target - POW target
* @param {number=} opts.poolSize - POW calculation pool size (by
* default equals to number of cores)
* @return {Promise.<number>} A promise that contains computed nonce for
* the given target when fulfilled.
*/