docs(api): first pass

Author: dignifiedquire

.gitignore

@@ -27,3 +27,4 @@ build/Release
 node_modules
 
 dist
+docs

.npmignore

@@ -26,4 +26,5 @@ build/Release
 # https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git
 node_modules
 
-test
+test
+docs

README.md

@@ -37,10 +37,6 @@ and [`browserify-sha3`](https://github.com/wanderer/browserify-sha3) are used.
 * [Examples](#examples)
   + [Multihash output](#multihash-output)
 * [API](#api)
-  + [`multihashing(buf, func, [length,] callback)`](#multihashingbuf-func-length-callback)
-  + [`digest(buf, func, [length,] callback)`](#digestbuf-func-length-callback)
-  + [`createHash(func)`](#createhashfunc)
-  + [`functions`](#functions)
 * [Maintainers](#maintainers)
 * [Contribute](#contribute)
 * [License](#license)
@@ -109,16 +105,16 @@ h(buf, (err, digest) => {
 ### Multihash output
 
 ```js
-> const multihashing = require('multihashing')
+> const multihashing = require('multihashing-async')
 > const buf = new Buffer('beep boop')
 
-> multihashing(buf, 'sha1'), (err, mh) => console.log(mh))
+> multihashing(buf, 'sha1', (err, mh) => console.log(mh))
 // => <Buffer 11 14 7c 83 57 57 7f 51 d4 f0 a8 d3 93 aa 1a aa fb 28 86 3d 94 21>
 
-> multihashing(buf, 'sha2-256', (err, mh) => onsole.log(mh))
+> multihashing(buf, 'sha2-256', (err, mh) => console.log(mh))
 // => <Buffer 12 20 90 ea 68 8e 27 5d 58 05 67 32 50 32 49 2b 59 7b c7 72 21 c6 24 93 e7 63 30 b8 5d dd a1 91 ef 7c>
 
-> multihashing(buf, 'sha2-512'), (err, mh) => console.log(mh))
+> multihashing(buf, 'sha2-512', (err, mh) => console.log(mh))
 // => <Buffer 13 40 14 f3 01 f3 1b e2 43 f3 4c 56 68 93 78 83 77 1f a3 81 00 2f 1a aa 5f 31 b3 f7 8e 50 0b 66 ff 2f 4f 8e a5 e3 c9 f5 a6 1b d0 73 e2 45 2c 48 04 84 b0 ...>
 ```
 

example.js

@@ -0,0 +1,19 @@
+'use strict'
+
+const multihashing = require('multihashing-async')
+const buf = new Buffer('beep boop')
+
+function print (err, mh) {
+  if (err) {
+    throw err
+  }
+  console.log(mh)
+}
+multihashing(buf, 'sha1', print)
+// => <Buffer 11 14 7c 83 57 57 7f 51 d4 f0 a8 d3 93 aa 1a aa fb 28 86 3d 94 21>
+
+multihashing(buf, 'sha2-256', print)
+// => <Buffer 12 20 90 ea 68 8e 27 5d 58 05 67 32 50 32 49 2b 59 7b c7 72 21 c6 24 93 e7 63 30 b8 5d dd a1 91 ef 7c>
+
+multihashing(buf, 'sha2-512', print)
+// => <Buffer 13 40 14 f3 01 f3 1b e2 43 f3 4c 56 68 93 78 83 77 1f a3 81 00 2f 1a aa 5f 31 b3 f7 8e 50 0b 66 ff 2f 4f 8e a5 e3 c9 f5 a6 1b d0 73 e2 45 2c 48 04 84 b0 ...>

package.json

@@ -11,9 +11,10 @@
     "test:browser": "aegir-test browser",
     "test:node": "aegir-test node",
     "lint": "aegir-lint",
-    "release": "aegir-release",
-    "release-minor": "aegir-release minor",
-    "release-major": "aegir-release major",
+    "docs": "aegir-docs",
+    "release": "aegir-release --docs",
+    "release-minor": "aegir-release minor --docs",
+    "release-major": "aegir-release major --docs",
     "build": "aegir-build",
     "coverage": "aegir-coverage",
     "coverage-publish": "aegir-coverage publish",
@@ -42,10 +43,10 @@
     "nodeify": "^1.0.0"
   },
   "devDependencies": {
-    "aegir": "^9.1.2",
+    "aegir": "^9.3.0",
     "benchmark": "^2.1.2",
     "chai": "^3.5.0",
-    "pre-commit": "^1.1.3"
+    "pre-commit": "^1.2.2"
   },
   "engines": {
     "node": ">=4.0.0"
@@ -60,4 +61,4 @@
     "Richard Littauer <[email protected]>",
     "npm-to-cdn-bot (by Forbes Lindesay) <[email protected]>"
   ]
-}
+}

src/index.js

@@ -5,6 +5,16 @@ const crypto = require('./crypto')
 
 module.exports = Multihashing
 
+/**
+ * Hash the given `buf` using the algorithm specified
+ * by `func`.
+ *
+ * @param {Buffer} buf - The value to hash.
+ * @param {number|string} func - The algorithm to use.
+ * @param {number} [length] - Optionally trim the result to this length.
+ * @param {function(Error, Buffer)} callback
+ * @returns {undefined}
+ */
 function Multihashing (buf, func, length, callback) {
   if (typeof length === 'function') {
     callback = length
@@ -24,11 +34,25 @@ function Multihashing (buf, func, length, callback) {
   })
 }
 
+/**
+ * The `buffer` module for easy use in the browser.
+ *
+ * @type {Buffer}
+ */
 Multihashing.Buffer = Buffer // for browser things
 
-// expose multihash itself, to avoid silly double requires.
+/**
+ * Expose multihash itself, to avoid silly double requires.
+ */
 Multihashing.multihash = multihash
 
+/**
+ * @param {Buffer} buf - The value to hash.
+ * @param {number|string} func - The algorithm to use.
+ * @param {number} [length] - Optionally trim the result to this length.
+ * @param {function(Error, Buffer)} callback
+ * @returns {undefined}
+ */
 Multihashing.digest = function (buf, func, length, callback) {
   if (typeof length === 'function') {
     callback = length
@@ -60,6 +84,11 @@ Multihashing.digest = function (buf, func, length, callback) {
   hash(buf, cb)
 }
 
+/**
+ * @param {string|number} func
+ *
+ * @returns {function} - The to `func` corresponding hash function.
+ */
 Multihashing.createHash = function (func) {
   func = multihash.coerceCode(func)
   if (!Multihashing.functions[func]) {
@@ -69,6 +98,10 @@ Multihashing.createHash = function (func) {
   return Multihashing.functions[func]
 }
 
+/**
+ * Mapping of multihash codes to their hashing functions.
+ * @type {Object}
+ */
 Multihashing.functions = {
   // sha1
   0x11: crypto.sha1,