[WIP] Awesome API Documentation

.gitignore

@@ -33,3 +33,4 @@ 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,15 +23,6 @@
     - [Gotchas](#gotchas)
 - [Usage](#usage)
 - [API](#api)
-  - [`new CID(codec[, version, hash])`](#new-cidcodec-version-hash)
-  - [`.codec`](#codec)
-  - [`.version`](#version)
-  - [`.hash`](#hash)
-  - [`.buffer`](#buffer)
-  - [`.toString()`](#tostring)
-  - [`.toJSON()`](#tojson)
-  - [`CID.isCID(other)`](#cidiscidother)
-  - [`CID.codecs`](#cidcodecs)
 - [Contribute](#contribute)
 - [License](#license)
 
@@ -79,36 +70,6 @@ const cid = new CID(base58Multihash)
 
 ## API
 
-### Constructor
-
-- `new CID(<version>, <codec>, <multihash>)`
-- `new CID(<cidStr>)`
-- `new CID(<cid.buffer>)`
-- `new CID(<multihash>)`
-- `new CID(<bs58 encoded multihash>)`
-
-### `.codec`
-
-### `.version`
-
-### `.hash`
-
-### `.buffer`
-
-### `.toV0()`
-
-### `.toV1()`
-
-### `.toBaseEncodedString(base)`
-
-Defaults to 'base58btc'
-
-### `.toJSON()`
-
-### `CID.isCID(other)`
-
-### `CID.codecs`
-
 ## Contribute
 
 [![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/contributing.md)

documentation.yml

@@ -0,0 +1,4 @@
+toc:
+  - CID
+  - SerializedCID
+  - Codecs

src/codecs.js

@@ -1,9 +1,18 @@
 'use strict'
 
-/*
- * Consult table at: https://github.com/multiformats/multicodec
+/**
+ * List of multicodecs available.
+ *
+ * Consult table at: https://github.com/multiformats/multicodec for more details.
+ * @alias Codecs
+ *
+ * @type {Object}
+ * @param {Buffer} raw
+ * @param {Buffer} dag-pb
+ * @param {Buffer} dag-cbor
+ * @param {Buffer} eth-block
+ * @param {Buffer} eth-tx
  */
-
 module.exports = {
   raw: new Buffer('00', 'hex'),
   'dag-pb': new Buffer('70', 'hex'),

src/index.js

@@ -6,10 +6,24 @@ const multicodec = require('multicodec')
 
 const codecs = require('./codecs')
 
-// CID: <mbase><version><mcodec><mhash>
+/**
+ * @typedef {Object} SerializedCID
+ * @param {string} codec
+ * @param {number} version
+ * @param {Buffer} multihash
+ *
+ */
 
+/**
+ * Class representing a CID `<mbase><version><mcodec><mhash>`
+ * , as defined in [ipld/cid](https://github.com/ipld/cid).
+ * @class CID
+ */
 class CID {
-  /*
+  /**
+   * Construct a CID.
+   *
+   * Rough algorithm of construction:
    * if (str)
    *   if (1st char is on multibase table) -> CID String
    *   else -> bs58 encoded multihash
@@ -19,7 +33,19 @@ class CID {
    * else if (Number)
    *   -> construct CID by parts
    *
-   * ..if only JS had traits..
+   * @param {string} version
+   * @param {number} [codec]
+   * @param {Buffer} [multihash]
+   *
+   * @example
+   * const CID = require('cids')
+   *
+   * // V1 CID
+   * const cid = new CID(CID.codecs.raw, 1, myhash)
+   *
+   * // V0 CID
+   * const cid = new CID(base58Multihash)
+   *
    */
   constructor (version, codec, multihash) {
     if (typeof version === 'string') {
@@ -54,20 +80,40 @@ class CID {
         throw new Error('version must be a number equal to 0 or 1')
       }
       mh.validate(multihash)
+
+      /**
+       * @type {string}
+       */
       this.codec = codec
+
+      /**
+       * @type {number}
+       */
       this.version = version
+
+      /**
+       * @type {Buffer}
+       */
       this.multihash = multihash
     }
   }
 
+  /**
+   * The CID as a `Buffer`
+   *
+   * @return {Buffer}
+   * @readonly
+   *
+   * @memberOf CID
+   */
   get buffer () {
     switch (this.version) {
       case 0:
         return this.multihash
       case 1:
         return Buffer.concat([
-          Buffer('01', 'hex'),
-          Buffer(codecs[this.codec]),
+          new Buffer('01', 'hex'),
+          new Buffer(codecs[this.codec]),
           this.multihash
         ])
       default:
@@ -83,7 +129,14 @@ class CID {
     return this.buffer
   }
 
-  /* defaults to base58btc */
+  /**
+   * Encode the CID into a string.
+   *
+   * @param {string} base - Mutlibase to use for encoding
+   * @return {string}
+   *
+   * @memberOf CID
+   */
   toBaseEncodedString (base) {
     base = base || 'base58btc'
 
@@ -96,7 +149,13 @@ class CID {
         throw new Error('Unsupported version')
     }
   }
-
+  /**
+   * Serialize to a plain object.
+   *
+   * @return {SerializedCID}
+   *
+   * @memberOf CID
+   */
   toJSON () {
     return {
       codec: this.codec,
@@ -105,16 +164,37 @@ class CID {
     }
   }
 
+  /**
+   * Compare equality with another CID.
+   *
+   * @param {CID} other
+   * @return {boolean}
+   *
+   * @memberOf CID
+   */
   equals (other) {
     return this.codec === other.codec &&
       this.version === other.version &&
       this.multihash.equals(other.multihash)
   }
+
+  /**
+   * Test if the given input is a valid CID object.
+   *
+   * @param {any} other
+   * @return {boolean}
+   *
+   */
+  static isCID (other) {
+    return other.constructor.name === 'CID'
+  }
 }
 
+/**
+ * @type {Codecs}
+ * @memberof CID
+ * @static
+ */
 CID.codecs = codecs
-CID.isCID = (other) => {
-  return other.constructor.name === 'CID'
-}
 
 module.exports = CID