docs(api): first pass

Author: dignifiedquire

.gitignore

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

.npmignore

@@ -31,4 +31,5 @@ build
 # 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

@@ -23,16 +23,6 @@ This is the [multihash](//github.com/multiformats/multihash) implementation in N
     - [Gotchas](#gotchas)
 - [Usage](#usage)
 - [API](#api)
-  - [`decode(buf)`](#decodebuf)
-  - [`encode(digest, hashfn[, length])`](#encodedigest-hashfn-length)
-  - [`toHexString(multihash)`](#tohexstringmultihash)
-  - [`fromHexString(string)`](#fromhexstringstring)
-  - [`toB58String(multihash)`](#tob58stringmultihash)
-  - [`fromB58String(string)`](#fromb58stringstring)
-  - [`coerceCode(name)`](#coercecodename)
-  - [`isAppCode(code)`](#isappcodecode)
-  - [`isValidCode(code)`](#isvalidcodecode)
-  - [`validate(multihash)`](#validatemultihash)
 - [Maintainers](#maintainers)
 - [Contribute](#contribute)
 - [License](#license)
@@ -87,96 +77,6 @@ You will need to use Node.js `Buffer` API compatible, if you are running inside
 
 ## API
 
-### `decode(buf)`
-
-- `buf: Buffer`
-
-Decode a hash from the given multihash.
-
-Returns an object of the form,
-
-```js
-{
-  code: Number,
-  name: String,
-  length: Number,
-  digest: Buffer
-}
-```
-
-### `encode(digest, hashfn[, length])`
-
-- `digest: Buffer`
-- `hashfn: String|Number`
-- `length: Number` (optional)
-
-Encode a hash digest along with the specified function code.
-
-> Note: the length is derived from the length of the digest itself.
-
-Returns a buffer.
-
-### `toHexString(multihash)`
-
-- `multihash: Buffer`
-
-Convert the given multihash to a hex encoded string.
-
-Returns a string.
-
-### `fromHexString(string)`
-
-- `string: String`
-
-Convert the given hex encoded string to a multihash (a `Buffer`).
-
-Returns a buffer.
-
-### `toB58String(multihash)`
-
-- `multihash: Buffer`
-
-Convert the given multihash to a base58 encoded string.
-
-Returns a string.
-
-### `fromB58String(string)`
-
-- `string: String`
-
-Convert the given base58 encoded string to a multihash (a `Buffer`).
-
-Returns a buffer.
-
-### `coerceCode(name)`
-
-- `name: String|Number`
-
-Converts a given hash function into the matching code. If passed a number it will return the number if it's a valid code.
-
-Returns a number.
-
-### `isAppCode(code)`
-
-- `code: Number`
-
-Checks wether a code is part of the app range.
-
-Returns a boolean.
-
-### `isValidCode(code)`
-
-- `code: Number`
-
-Checks whether a multihash code is valid.
-
-Returns a boolean.
-
-### `validate(multihash)`
-
-- `multihash: Buffer`
-
-Check if the given buffer is a valid multihash. Throws an error if it is not valid.
 
 ## Maintainers
 

example.js

@@ -0,0 +1,16 @@
+'use strict'
+
+const multihash = require('multihashes')
+const buf = new Buffer('0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33', 'hex')
+
+const encoded = multihash.encode(buf, 'sha1')
+console.log(encoded)
+// => <Buffer 11 14 0b ee c7 b5 ea 3f 0f db c9 5d 0d d4 7f 3c 5b c2 75 da 8a 33>
+
+multihash.decode(encoded)
+// => {
+//      code: 17,
+//      name: 'sha1',
+//      length: 20,
+//      digest: <Buffer 0b ee c7 b5 ea 3f 0f db c9 5d 0d d4 7f 3c 5b c2 75 da 8a 33>
+//    }

package.json

@@ -9,9 +9,10 @@
     "test:browser": "aegir-test browser",
     "build": "aegir-build",
     "test": "aegir-test",
-    "release": "aegir-release",
-    "release-minor": "aegir-release --type minor",
-    "release-major": "aegir-release --type major",
+    "docs": "aegir-docs",
+    "release": "aegir-release --docs",
+    "release-minor": "aegir-release --type minor --docs",
+    "release-major": "aegir-release --type major --docs",
     "coverage": "aegir-coverage",
     "coverage-publish": "aegir-coverage publish"
   },
@@ -37,13 +38,13 @@
     "url": "https://github.com/multiformats/js-multihash/issues"
   },
   "dependencies": {
-    "bs58": "^3.0.0"
+    "bs58": "^3.1.0"
   },
   "devDependencies": {
-    "aegir": "^9.1.2",
+    "aegir": "^9.3.0",
     "buffer-equal": "1.0.0",
     "chai": "^3.5.0",
-    "pre-commit": "^1.1.2"
+    "pre-commit": "^1.2.2"
   },
   "contributors": [
     "David Dias <[email protected]>",
@@ -56,4 +57,4 @@
     "nginnever <[email protected]>",
     "npm-to-cdn-bot (by Forbes Lindesay) <[email protected]>"
   ]
-}
+}

src/index.js

@@ -1,39 +1,73 @@
+/**
+ * Multihash implementation in JavaScript.
+ *
+ * @module multihash
+ */
 'use strict'
 
 const bs58 = require('bs58')
 
 const cs = require('./constants')
 
-exports.toHexString = function toHexString (m) {
-  if (!Buffer.isBuffer(m)) {
+/**
+ * Convert the given multihash to a hex encoded string.
+ *
+ * @param {Buffer} hash
+ * @returns {string}
+ */
+exports.toHexString = function toHexString (hash) {
+  if (!Buffer.isBuffer(hash)) {
     throw new Error('must be passed a buffer')
   }
 
-  return m.toString('hex')
+  return hash.toString('hex')
 }
 
-exports.fromHexString = function fromHexString (s) {
-  return new Buffer(s, 'hex')
+/**
+ * Convert the given hex encoded string to a multihash.
+ *
+ * @param {string} hash
+ * @returns {Buffer}
+ */
+exports.fromHexString = function fromHexString (hash) {
+  return new Buffer(hash, 'hex')
 }
 
-exports.toB58String = function toB58String (m) {
-  if (!Buffer.isBuffer(m)) {
+/**
+ * Convert the given multihash to a base58 encoded string.
+ *
+ * @param {Buffer} hash
+ * @returns {string}
+ */
+exports.toB58String = function toB58String (hash) {
+  if (!Buffer.isBuffer(hash)) {
     throw new Error('must be passed a buffer')
   }
 
-  return bs58.encode(m)
+  return bs58.encode(hash)
 }
 
-exports.fromB58String = function fromB58String (s) {
-  let encoded = s
-  if (Buffer.isBuffer(s)) {
-    encoded = s.toString()
+/**
+ * Convert the given base58 encoded string to a multihash.
+ *
+ * @param {string|Buffer} hash
+ * @returns {Buffer}
+ */
+exports.fromB58String = function fromB58String (hash) {
+  let encoded = hash
+  if (Buffer.isBuffer(hash)) {
+    encoded = hash.toString()
   }
 
   return new Buffer(bs58.decode(encoded))
 }
 
-// Decode a hash from the given Multihash.
+/**
+ * Decode a hash from the given multihash.
+ *
+ * @param {Buffer} buf
+ * @returns {{code: number, name: string, length: number, digest: Buffer}} result
+ */
 exports.decode = function decode (buf) {
   exports.validate(buf)
 
@@ -47,8 +81,16 @@ exports.decode = function decode (buf) {
   }
 }
 
-// Encode a hash digest along with the specified function code.
-// Note: the length is derived from the length of the digest itself.
+/**
+ *  Encode a hash digest along with the specified function code.
+ *
+ * > **Note:** the length is derived from the length of the digest itself.
+ *
+ * @param {Buffer} digest
+ * @param {string|number} code
+ * @param {number} [length]
+ * @returns {Buffer}
+ */
 exports.encode = function encode (digest, code, length) {
   if (!digest || !code) {
     throw new Error('multihash encode requires at least two args: digest, code')
@@ -76,7 +118,12 @@ exports.encode = function encode (digest, code, length) {
   return Buffer.concat([new Buffer([hashfn, length]), digest])
 }
 
-// Converts a hashfn name into the matching code
+/**
+ * Converts a hash function name into the matching code.
+ * If passed a number it will return the number if it's a valid code.
+ * @param {string|number} name
+ * @returns {number}
+ */
 exports.coerceCode = function coerceCode (name) {
   let code = name
 
@@ -98,12 +145,22 @@ exports.coerceCode = function coerceCode (name) {
   return code
 }
 
-// Checks wether a code is part of the app range
+/**
+ * Checks wether a code is part of the app range
+ *
+ * @param {number} code
+ * @returns {boolean}
+ */
 exports.isAppCode = function appCode (code) {
   return code > 0 && code < 0x10
 }
 
-// Checks whether a multihash code is valid.
+/**
+ * Checks whether a multihash code is valid.
+ *
+ * @param {number} code
+ * @returns {boolean}
+ */
 exports.isValidCode = function validCode (code) {
   if (exports.isAppCode(code)) {
     return true
@@ -116,6 +173,13 @@ exports.isValidCode = function validCode (code) {
   return false
 }
 
+/**
+ * Check if the given buffer is a valid multihash. Throws an error if it is not valid.
+ *
+ * @param {Buffer} multihash
+ * @returns {undefined}
+ * @throws {Error}
+ */
 exports.validate = function validate (multihash) {
   if (!(Buffer.isBuffer(multihash))) {
     throw new Error('multihash must be a Buffer')