Fix building documentation

documentation.yml

@@ -0,0 +1,18 @@
+toc:
+  - SecureTrie
+  - Trie
+  - name: Merkle Proof
+    description: |
+      Static functions for creating/verifying a merkle proof.
+    children:
+      - prove
+      - verifyProof
+  - name: Internal Util Functions
+    description: |
+      These are not exposed.
+    children:
+      - addHexPrefix
+      - asyncFirstSeries
+      - callTogether
+      - doKeysMatch
+      - matchingNibbleLength

package.json

@@ -13,7 +13,7 @@
     "test:node": "babel-tape-runner ./test/*.js",
     "babel": "npx babel src --out-dir ./",
     "build": "npm run babel && mkdir -p dist && browserify --s Trie index.js -o dist/trie.js -t [ babelify --presets [ @babel/preset-env ] ]",
-    "build:docs": "documentation --github  -f md ./index.js ./secure.js ./proof.js > ./docs/index-template.md"
+    "build:docs": "documentation build ./src/** -f md --shallow ./src/index.js ./src/secure.js ./src/proof.js > ./docs/index.md --github --config documentation.yml --markdown-toc false"
   },
   "author": {
     "name": "mjbecze",
@@ -51,7 +51,7 @@
     "babelify": "^10.0.0",
     "browserify": "^13.0.0",
     "coveralls": "^2.11.6",
-    "documentation": "^3.0.4",
+    "documentation": "^8.1.2",
     "ethereumjs-testing": "0.0.1",
     "istanbul": "^0.4.1",
     "karma": "^1.7.1",

src/baseTrie.js

@@ -17,6 +17,7 @@ module.exports = Trie
 /**
  * Use `require('merkel-patricia-tree')` for the base interface. In Ethereum applications stick with the Secure Trie Overlay `require('merkel-patricia-tree/secure')`. The API for the raw and the secure interface are about the same
  * @class Trie
+ * @public
  * @param {Object} [db] An instance of [levelup](https://github.com/rvagg/node-levelup/) or a compatible API. If the db is `null` or left undefined, then the trie will be stored in memory via [memdown](https://github.com/rvagg/memdown)
  * @param {Buffer|String} [root] A hex `String` or `Buffer` for the root of a previously stored trie
  * @prop {Buffer} root The current root of the `trie`
@@ -56,6 +57,7 @@ function Trie (db, root) {
 /**
  * Gets a value given a `key`
  * @method get
+ * @memberof Trie
  * @param {Buffer|String} key - the key to search for
  * @param {Function} cb A callback `Function` which is given the arguments `err` - for errors that may have occured and `value` - the found value in a `Buffer` or if no value was found `null`
  */
@@ -77,6 +79,7 @@ Trie.prototype.get = function (key, cb) {
 /**
  * Stores a given `value` at the given `key`
  * @method put
+ * @memberof Trie
  * @param {Buffer|String} key
  * @param {Buffer|String} Value
  * @param {Function} cb A callback `Function` which is given the argument `err` - for errors that may have occured
@@ -112,6 +115,7 @@ Trie.prototype.put = function (key, value, cb) {
 /**
  * deletes a value given a `key`
  * @method del
+ * @memberof Trie
  * @param {Buffer|String} key
  * @param {Function} callback the callback `Function`
  */
@@ -138,6 +142,7 @@ Trie.prototype.del = function (key, cb) {
 /**
  * Retrieves a raw value in the underlying db
  * @method getRaw
+ * @memberof Trie
  * @param {Buffer} key
  * @param {Function} callback A callback `Function`, which is given the arguments `err` - for errors that may have occured and `value` - the found value in a `Buffer` or if no value was found `null`.
  */
@@ -192,6 +197,7 @@ Trie.prototype._putRaw = function (key, val, cb) {
 /**
  * Writes a value directly to the underlining db
  * @method putRaw
+ * @memberof Trie
  * @param {Buffer|String} key The key as a `Buffer` or `String`
  * @param {Buffer} value The value to be stored
  * @param {Function} callback A callback `Function`, which is given the argument `err` - for errors that may have occured
@@ -201,6 +207,7 @@ Trie.prototype.putRaw = Trie.prototype._putRaw
 /**
  * Removes a raw value in the underlying db
  * @method delRaw
+ * @memberof Trie
  * @param {Buffer|String} key
  * @param {Function} callback A callback `Function`, which is given the argument `err` - for errors that may have occured
  */
@@ -236,6 +243,7 @@ Trie.prototype._batchNodes = function (opStack, cb) {
  * Trys to find a path to the node for the given key
  * It returns a `stack` of nodes to the closet node
  * @method findPath
+ * @memberof Trie
  * @param {String|Buffer} - key - the search key
  * @param {Function} - cb - the callback function. Its is given the following
  * arguments
@@ -345,6 +353,7 @@ Trie.prototype._findDbNodes = function (onFound, cb) {
 /**
  * Updates a node
  * @method _updateNode
+ * @private
  * @param {Buffer} key
  * @param {Buffer| String} value
  * @param {Array} keyRemainder
@@ -521,6 +530,7 @@ Trie.prototype._walkTrie = function (root, onNode, onDone) {
 /**
  * saves a stack
  * @method _saveStack
+ * @private
  * @param {Array} key - the key. Should follow the stack
  * @param {Array} stack - a stack of nodes to the value given by the key
  * @param {Array} opStack - a stack of levelup operations to commit at the end of this funciton
@@ -707,6 +717,7 @@ Trie.prototype._formatNode = function (node, topLevel, remove, opStack) {
 /**
  * The `data` event is given an `Object` hat has two properties; the `key` and the `value`. Both should be Buffers.
  * @method createReadStream
+ * @memberof Trie
  * @return {stream.Readable} Returns a [stream](https://nodejs.org/dist/latest-v5.x/docs/api/stream.html#stream_class_stream_readable) of the contents of the `trie`
  */
 Trie.prototype.createReadStream = function () {
@@ -722,6 +733,7 @@ Trie.prototype.copy = function () {
 /**
  * The given hash of operations (key additions or deletions) are executed on the DB
  * @method batch
+ * @memberof Trie
  * @example
  * var ops = [
  *    { type: 'del', key: 'father' }
@@ -751,6 +763,7 @@ Trie.prototype.batch = function (ops, cb) {
 /**
  * Checks if a given root exists
  * @method checkRoot
+ * @memberof Trie
  * @param {Buffer} root
  * @param {Function} cb
  */

src/checkpoint-interface.js

@@ -32,6 +32,7 @@ function checkpointInterface (trie) {
 /**
  * Creates a checkpoint that can later be reverted to or committed. After this is called, no changes to the trie will be permanently saved until `commit` is called
  * @method checkpoint
+ * @private
  */
 function checkpoint () {
   var self = this
@@ -45,6 +46,7 @@ function checkpoint () {
 /**
  * commits a checkpoint to disk
  * @method commit
+ * @private
  * @param {Function} cb the callback
  */
 function commit (cb) {
@@ -68,6 +70,7 @@ function commit (cb) {
 /**
  * Reverts the trie to the state it was at when `checkpoint` was first called.
  * @method revert
+ * @private
  * @param {Function} cb the callback
  */
 function revert (cb) {

src/prioritizedTaskExecutor.js

@@ -2,6 +2,7 @@ module.exports = class PrioritizedTaskExecutor {
   /**
    * Executes tasks up to maxPoolSize at a time, other items are put in a priority queue.
    * @class PrioritizedTaskExecutor
+   * @private
    * @param {Number} maxPoolSize The maximum size of the pool
    * @prop {Number} maxPoolSize The maximum size of the pool
    * @prop {Number} currentPoolSize The current size of the pool
@@ -15,6 +16,7 @@ module.exports = class PrioritizedTaskExecutor {
 
   /**
    * Executes the task.
+   * @private
    * @param {Number} priority The priority of the task
    * @param {Function} task The function that accepts the callback, which must be called upon the task completion.
    */

src/proof.js

@@ -4,7 +4,7 @@ const matchingNibbleLength = require('./util').matchingNibbleLength
 
 /**
  * Returns a merkle proof for a given key
- * @method Trie.prove
+ * @method prove
  * @param {Trie} trie
  * @param {String} key
  * @param {Function} cb A callback `Function` (arguments {Error} `err`, {Array.<TrieNode>} `proof`)
@@ -30,7 +30,7 @@ exports.prove = function (trie, key, cb) {
 
 /**
  * Verifies a merkle proof for a given key
- * @method Trie.verifyProof
+ * @method verifyProof
  * @param {Buffer} rootHash
  * @param {String} key
  * @param {Array.<TrieNode>} proof

src/secure.js

@@ -5,6 +5,7 @@ const secureInterface = require('./secure-interface')
  * You can create a secure Trie where the keys are automatically hashed using **SHA3** by using `require('merkle-patricia-tree/secure')`. It has the same methods and constructor as `Trie`.
  * @class SecureTrie
  * @extends Trie
+ * @public
  */
 module.exports = class SecureTrie extends CheckpointTrie {
   constructor (...args) {

src/trieNode.js

@@ -191,6 +191,7 @@ function removeHexPrefix (val) {
 /**
  * Determines if a key has Arnold Schwarzenegger in it.
  * @method isTerminator
+ * @private
  * @param {Array} key - an hexprefixed array of nibbles
  */
 function isTerminator (key) {
@@ -200,6 +201,7 @@ function isTerminator (key) {
 /**
  * Converts a string OR a buffer to a nibble array.
  * @method stringToNibbles
+ * @private
  * @param {Buffer| String} key
  */
 function stringToNibbles (key) {
@@ -218,6 +220,7 @@ function stringToNibbles (key) {
 /**
  * Converts a nibble array into a buffer.
  * @method nibblesToBuffer
+ * @private
  * @param arr
  */
 function nibblesToBuffer (arr) {
@@ -231,6 +234,7 @@ function nibblesToBuffer (arr) {
 
 /**
  * Determines the node type.
+ * @private
  * @returns {String} - the node type
  *   - leaf - if the node is a leaf
  *   - branch - if the node is a branch

src/util.js

@@ -8,8 +8,9 @@ module.exports = {
 }
 
 /**
- * Returns the number of in order matching nibbles of two give nibble arrayes
+ * Returns the number of in order matching nibbles of two give nibble arrays
  * @method matchingNibbleLength
+ * @private
  * @param {Array} nib1
  * @param {Array} nib2
  */