Document pow module

lib/pow.js

@@ -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.
  */