Merge pull request #362 from whymarrh/update-jsdoc

Update JSDoc comments to add missing parameters

lib/bloom.js

@@ -3,9 +3,10 @@ const utils = require('ethereumjs-util')
 const byteSize = 256
 
 /**
- * drops leading zeroes from a buffer
+ * Drops leading zeroes from a buffer
  * @function dropLeadingZeroes
  * @param {Buffer} buff
+ * @returns {Buffer} a slice of the given buffer starting at the first non-zero entry
  */
 function dropLeadingZeroes (buff) {
   for (var i = 0; i < buff.length; i++) {
@@ -32,7 +33,7 @@ var Bloom = module.exports = function (bitvector) {
 /**
  * adds an element to a bit vector of a 64 byte bloom filter
  * @method add
- * @param {Buffer} element
+ * @param {Buffer} e the element to add
  */
 Bloom.prototype.add = function (e) {
   e = utils.keccak256(dropLeadingZeroes(e))
@@ -48,9 +49,10 @@ Bloom.prototype.add = function (e) {
 }
 
 /**
- * checks if an element is in the blooom
+ * checks if an element is in the bloom
  * @method check
- * @param {Buffer} element
+ * @param {Buffer} e the element to check
+ * @returns {boolean} Returns {@code true} if the element is in the bloom
  */
 Bloom.prototype.check = function (e) {
   e = utils.keccak256(dropLeadingZeroes(e))
@@ -69,9 +71,10 @@ Bloom.prototype.check = function (e) {
 }
 
 /**
- * checks if multple topics are in a bloom
- * @method check
- * @param {Buffer} element
+ * checks if multiple topics are in a bloom
+ * @method multiCheck
+ * @param {Buffer} topics
+ * @returns {boolean} Returns {@code true} if every topic is in the bloom
  */
 Bloom.prototype.multiCheck = function (topics) {
   var self = this

lib/opFns.js

@@ -799,9 +799,10 @@ function trap (err) {
 /**
  * Subtracts the amount needed for memory usage from `runState.gasLeft`
  * @method subMemUsage
+ * @param {Object} runState
  * @param {BN} offset
  * @param {BN} length
- * @return {String}
+ * @returns {String}
  */
 function subMemUsage (runState, offset, length) {
   // YP (225): access with zero length will not extend the memory
@@ -829,9 +830,10 @@ function subMemUsage (runState, offset, length) {
  * a string is instead returned. The function also subtracts the amount of
  * gas need for memory expansion.
  * @method memLoad
+ * @param {Object} runState
  * @param {BN} offset where to start reading from
  * @param {BN} length how far to read
- * @return {Buffer|String}
+ * @returns {Buffer|String}
  */
 function memLoad (runState, offset, length) {
   // check to see if we have enougth gas for the mem read
@@ -858,12 +860,13 @@ function memLoad (runState, offset, length) {
  * Stores bytes to memory. If an error occurs a string is instead returned.
  * The function also subtracts the amount of gas need for memory expansion.
  * @method memStore
+ * @param {Object} runState
  * @param {BN} offset where to start reading from
  * @param {Buffer} val
  * @param {BN} valOffset
  * @param {BN} length how far to read
  * @param {Boolean} skipSubMem
- * @return {Buffer|String}
+ * @returns {Buffer|String}
  */
 function memStore (runState, offset, val, valOffset, length, skipSubMem) {
   if (skipSubMem !== false) {

lib/runBlockchain.js

@@ -1,9 +1,10 @@
 const async = require('async')
 
 /**
- * processes blocks and adds them to the blockchain
+ * Processes blocks and adds them to the blockchain
  * @method onBlock
  * @param blockchain
+ * @param {Function} cb the callback function
  */
 module.exports = function (blockchain, cb) {
   var self = this

lib/runCall.js

@@ -19,6 +19,7 @@ const ERROR = exceptions.ERROR
  * @param opts.origin {Buffer} []
  * @param opts.to {Buffer}
  * @param opts.value {Buffer}
+ * @param {Function} cb the callback
  */
 module.exports = function (opts, cb) {
   var self = this

lib/stateManager.js

@@ -237,8 +237,8 @@ proto.getStateRoot = function (cb) {
 }
 
 /**
- * @param {Set} address
- * @param {cb} function
+ * @param {Set} addresses a set of addresses
+ * @param {Function} cb the callback function
  */
 proto.warmCache = function (addresses, cb) {
   this.cache.warm(addresses, cb)

tests/util.js

@@ -92,7 +92,7 @@ var format = exports.format = function (a, toZero, isHex) {
 /**
  * makeTx using JSON from tests repo
  * @param {[type]} txData the transaction object from tests repo
- * @return {Object}        object that will be passed to VM.runTx function
+ * @returns {Object}        object that will be passed to VM.runTx function
  */
 exports.makeTx = function (txData) {
   var tx = new Transaction()
@@ -261,7 +261,7 @@ exports.verifyLogs = function (logs, testData, t) {
 /**
  * toDecimal - converts buffer to decimal string, no leading zeroes
  * @param  {Buffer}
- * @return {String}
+ * @returns {String}
  */
 exports.toDecimal = function (buffer) {
   return new BN(buffer).toString()
@@ -270,7 +270,7 @@ exports.toDecimal = function (buffer) {
 /**
  * fromDecimal - converts decimal string to buffer
  * @param {String}
- *  @return {Buffer}
+ *  @returns {Buffer}
  */
 exports.fromDecimal = function (string) {
   return Buffer.from(new BN(string).toArray())
@@ -279,7 +279,7 @@ exports.fromDecimal = function (string) {
 /**
  * fromAddress - converts hexString address to 256-bit buffer
  * @param  {String} hexString address for example '0x03'
- * @return {Buffer}
+ * @returns {Buffer}
  */
 exports.fromAddress = function (hexString) {
   return utils.setLength(Buffer.from(new BN(hexString.slice(2), 16).toArray()), 32)
@@ -288,7 +288,7 @@ exports.fromAddress = function (hexString) {
 /**
  * toCodeHash - applies sha3 to hexCode
  * @param {String} hexCode string from tests repo
- * @return {Buffer}
+ * @returns {Buffer}
  */
 exports.toCodeHash = function (hexCode) {
   return utils.sha3(Buffer.from(hexCode.slice(2), 'hex'))
@@ -311,7 +311,7 @@ exports.makeBlockHeader = function (data) {
  * makeBlockFromEnv - helper to create a block from the env object in tests repo
  * @param {Object} env object from tests repo
  * @param {Object} transactions transactions for the block
- * @return {Object}  the block
+ * @returns {Object} the block
  */
 exports.makeBlockFromEnv = function (env, transactions) {
   return new Block({
@@ -327,7 +327,7 @@ exports.makeBlockFromEnv = function (env, transactions) {
  * @param {Object} exec    object from the tests repo
  * @param {Object} account that the executing code belongs to
  * @param {Object} block   that the transaction belongs to
- * @return {Object}        object that will be passed to VM.runCode function
+ * @returns {Object}       object that will be passed to VM.runCode function
  */
 exports.makeRunCodeData = function (exec, account, block) {
   return {