From dd26a290cae03d11bdf188cb6ea95ff8c57a108e Mon Sep 17 00:00:00 2001 From: Whymarrh Whitby Date: Wed, 26 Sep 2018 15:26:09 -0230 Subject: [PATCH 1/3] Update JSDoc comments to add missing parameters --- lib/bloom.js | 15 +++++++++------ lib/opFns.js | 3 +++ lib/runBlockchain.js | 1 + lib/runCall.js | 1 + lib/stateManager.js | 4 ++-- 5 files changed, 16 insertions(+), 8 deletions(-) diff --git a/lib/bloom.js b/lib/bloom.js index 2cf25af99d..edba7f6f3c 100644 --- a/lib/bloom.js +++ b/lib/bloom.js @@ -6,6 +6,7 @@ const byteSize = 256 * 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 diff --git a/lib/opFns.js b/lib/opFns.js index f1e2b57713..3295f65ee4 100644 --- a/lib/opFns.js +++ b/lib/opFns.js @@ -799,6 +799,7 @@ 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} @@ -829,6 +830,7 @@ 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} @@ -858,6 +860,7 @@ 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 diff --git a/lib/runBlockchain.js b/lib/runBlockchain.js index 2ceca40134..bc2bd99ced 100644 --- a/lib/runBlockchain.js +++ b/lib/runBlockchain.js @@ -4,6 +4,7 @@ const async = require('async') * 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 diff --git a/lib/runCall.js b/lib/runCall.js index 2d6d600410..7581e4d511 100644 --- a/lib/runCall.js +++ b/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 diff --git a/lib/stateManager.js b/lib/stateManager.js index 5986e45989..61bd5592c2 100644 --- a/lib/stateManager.js +++ b/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) From 6c831eab86a598ee305a271892a7f2b1aa7c870d Mon Sep 17 00:00:00 2001 From: Whymarrh Whitby Date: Fri, 5 Oct 2018 11:37:20 -0230 Subject: [PATCH 2/3] Fix formatting of JSDoc comments --- lib/bloom.js | 2 +- lib/runBlockchain.js | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/bloom.js b/lib/bloom.js index edba7f6f3c..e123828ad0 100644 --- a/lib/bloom.js +++ b/lib/bloom.js @@ -3,7 +3,7 @@ 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 diff --git a/lib/runBlockchain.js b/lib/runBlockchain.js index bc2bd99ced..b05ae9aab3 100644 --- a/lib/runBlockchain.js +++ b/lib/runBlockchain.js @@ -1,7 +1,7 @@ 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 From e4621e710bee8764b18e93c7a4ba59a7b83112ff Mon Sep 17 00:00:00 2001 From: Whymarrh Whitby Date: Fri, 5 Oct 2018 11:45:12 -0230 Subject: [PATCH 3/3] Update JSDoc comments to s/@return /@returns / sed -i'' 's/@return /@returns /' --- lib/opFns.js | 6 +++--- tests/util.js | 14 +++++++------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/lib/opFns.js b/lib/opFns.js index 3295f65ee4..980d659f5d 100644 --- a/lib/opFns.js +++ b/lib/opFns.js @@ -802,7 +802,7 @@ function trap (err) { * @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 @@ -833,7 +833,7 @@ function subMemUsage (runState, offset, length) { * @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 @@ -866,7 +866,7 @@ function memLoad (runState, offset, length) { * @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) { diff --git a/tests/util.js b/tests/util.js index 0b8c409314..4046238e5e 100644 --- a/tests/util.js +++ b/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 {