docs(api): initial baseline setup

Author: dignifiedquire

.gitignore

@@ -3,3 +3,4 @@
 test/setup/tmp-disposable-nodes-addrs.json
 dist
 coverage
+docs

.npmignore

@@ -3,3 +3,4 @@ node_modules
 coverage
 
 test
+docs

documentation.yml

@@ -19,7 +19,8 @@
     "release-minor": "gulp release --type minor",
     "release-major": "gulp release --type major",
     "coverage": "gulp coverage",
-    "coverage-publish": "aegir-coverage publish"
+    "coverage-publish": "aegir-coverage publish",
+    "docs": "aegir-docs"
   },
   "dependencies": {
     "async": "^2.1.4",

package.json

@@ -5,6 +5,23 @@ const addToDagNodesTransform = require('../add-to-dagnode-transform')
 const promisify = require('promisify-es6')
 
 module.exports = (send) => {
+  /**
+   * Add content to IPFS.
+   *
+   * @alias add
+   * @method
+   * @param {(Buffer|Stream|Array)} files - The content to add.
+   * @param {function=} callback
+   * @returns {Promise}
+   *
+   * @memberof Api#
+   *
+   * @example
+   * api.add(new Buffer('hello world')).then((res) => {
+   *   console.log('saved with hash %s', res.hash)
+   * })
+   *
+   */
   return promisify((files, callback) => {
     const good = Buffer.isBuffer(files) ||
                isStream.isReadable(files) ||

src/api/add.js

@@ -4,16 +4,48 @@ const promisify = require('promisify-es6')
 
 module.exports = (send) => {
   return {
+    /**
+     * Show blocks currently on the wantlist.
+     *
+     * @alias bitswap.wantlist
+     * @method
+     * @param {Function} [callback]
+     *
+     * @returns {Promise}
+     * @memberof Api#
+     */
     wantlist: promisify((callback) => {
       send({
         path: 'bitswap/wantlist'
       }, callback)
     }),
+    /**
+     * Show some diagnostic information on the bitswap agent.
+     *
+     * @alias bitswap.stat
+     * @method
+     * @param {Function} [callback]
+     *
+     * @returns {Promise}
+     * @memberof Api#
+     */
     stat: promisify((callback) => {
       send({
         path: 'bitswap/stat'
       }, callback)
     }),
+    /**
+     * Remove a given block from your wantlist.
+     *
+     * @alias bitswap.unwant
+     * @method
+     * @param {*} args
+     * @param {Object} opts
+     * @param {Function} [callback]
+     *
+     * @returns {Promise}
+     * @memberof Api#
+     */
     unwant: promisify((args, opts, callback) => {
       if (typeof (opts) === 'function') {
         callback = opts

src/api/bitswap.js

@@ -8,6 +8,12 @@ const CID = require('cids')
 
 module.exports = (send) => {
   return {
+    /**
+     * @alias block.get
+     * @method
+     * @returns {Promise|undefined}
+     * @memberof Api#
+     */
     get: promisify((args, opts, callback) => {
       // TODO this needs to be adjusted with the new go-ipfs http-api
       if (args && CID.isCID(args)) {
@@ -38,6 +44,13 @@ module.exports = (send) => {
         }
       })
     }),
+
+    /**
+     * @alias block.stat
+     * @method
+     * @returns {Promise|undefined}
+     * @memberof Api#
+     */
     stat: promisify((args, opts, callback) => {
       // TODO this needs to be adjusted with the new go-ipfs http-api
       if (args && CID.isCID(args)) {
@@ -62,6 +75,13 @@ module.exports = (send) => {
         })
       })
     }),
+
+    /**
+     * @alias block.put
+     * @method
+     * @returns {Promise|undefined}
+     * @memberof Api#
+     */
     put: promisify((block, cid, callback) => {
       // TODO this needs to be adjusted with the new go-ipfs http-api
       if (typeof cid === 'function') {

src/api/block.js

@@ -4,6 +4,12 @@ const promisify = require('promisify-es6')
 
 module.exports = (send) => {
   return {
+    /**
+     * @alias bootstrap.add
+     * @method
+     * @returns {Promise|undefined}
+     * @memberof Api#
+     */
     add: promisify((args, opts, callback) => {
       if (typeof opts === 'function' &&
           !callback) {
@@ -30,6 +36,13 @@ module.exports = (send) => {
         qs: opts
       }, callback)
     }),
+
+    /**
+     * @alias bootstrap.rm
+     * @method
+     * @returns {Promise|undefined}
+     * @memberof Api#
+     */
     rm: promisify((args, opts, callback) => {
       if (typeof opts === 'function' &&
           !callback) {
@@ -56,6 +69,13 @@ module.exports = (send) => {
         qs: opts
       }, callback)
     }),
+
+    /**
+     * @alias bootstrap.list
+     * @method
+     * @returns {Promise|undefined}
+     * @memberof Api#
+     */
     list: promisify((opts, callback) => {
       if (typeof (opts) === 'function') {
         callback = opts

src/api/bootstrap.js

@@ -4,6 +4,12 @@ const promisify = require('promisify-es6')
 const cleanMultihash = require('../clean-multihash')
 
 module.exports = (send) => {
+  /**
+   * @alias cat
+   * @method
+   * @returns {Promise|undefined}
+   * @memberof Api#
+   */
   return promisify((hash, opts, callback) => {
     if (typeof opts === 'function') {
       callback = opts

src/api/cat.js

@@ -3,6 +3,12 @@
 const promisify = require('promisify-es6')
 
 module.exports = (send) => {
+  /**
+   * @alias commands
+   * @method
+   * @returns {Promise|undefined}
+   * @memberof Api#
+   */
   return promisify((callback) => {
     send({
       path: 'commands'

src/api/commands.js

@@ -5,6 +5,12 @@ const promisify = require('promisify-es6')
 
 module.exports = (send) => {
   return {
+    /**
+     * @alias config.get
+     * @method
+     * @returns {Promise|undefined}
+     * @memberof Api#
+     */
     get: promisify((key, callback) => {
       if (typeof key === 'function') {
         callback = key
@@ -30,6 +36,12 @@ module.exports = (send) => {
         callback(null, response.Value)
       })
     }),
+    /**
+     * @alias config.set
+     * @method
+     * @returns {Promise|undefined}
+     * @memberof Api#
+     */
     set: promisify((key, value, opts, callback) => {
       if (typeof opts === 'function') {
         callback = opts
@@ -63,6 +75,12 @@ module.exports = (send) => {
         buffer: true
       }, callback)
     }),
+    /**
+     * @alias config.replace
+     * @method
+     * @returns {Promise|undefined}
+     * @memberof Api#
+     */
     replace: promisify((config, callback) => {
       if (typeof config === 'object') {
         config = streamifier.createReadStream(new Buffer(JSON.stringify(config)))

src/api/config.js

@@ -7,6 +7,12 @@ const promisify = require('promisify-es6')
 module.exports = (send) => {
   const add = addCmd(send)
 
+  /**
+   * @alias createAddStream
+   * @method
+   * @returns {Promise|undefined}
+   * @memberof Api#
+   */
   return promisify((callback) => {
     const tuples = []
 

src/api/create-add-stream.js

@@ -4,6 +4,12 @@ const promisify = require('promisify-es6')
 
 module.exports = (send) => {
   return {
+    /**
+     * @alias dht.findprovs
+     * @method
+     * @returns {Promise|undefined}
+     * @memberof Api#
+     */
     findprovs: promisify((args, opts, callback) => {
       if (typeof opts === 'function' &&
           !callback) {
@@ -25,6 +31,13 @@ module.exports = (send) => {
         qs: opts
       }, callback)
     }),
+
+    /**
+     * @alias dht.get
+     * @method
+     * @returns {Promise|undefined}
+     * @memberof Api#
+     */
     get: promisify((key, opts, callback) => {
       if (typeof opts === 'function' &&
           !callback) {
@@ -70,6 +83,13 @@ module.exports = (send) => {
         qs: opts
       }, handleResult.bind(null, callback))
     }),
+
+    /**
+     * @alias dht.put
+     * @method
+     * @returns {Promise|undefined}
+     * @memberof Api#
+     */
     put: promisify((key, value, opts, callback) => {
       if (typeof opts === 'function' &&
           !callback) {

src/api/dht.js

@@ -4,6 +4,12 @@ const promisify = require('promisify-es6')
 
 module.exports = (send) => {
   return {
+    /**
+     * @alias diag.net
+     * @method
+     * @returns {Promise|undefined}
+     * @memberof Api#
+     */
     net: promisify((opts, callback) => {
       if (typeof (opts) === 'function') {
         callback = opts
@@ -15,6 +21,13 @@ module.exports = (send) => {
         qs: opts
       }, callback)
     }),
+
+    /**
+     * @alias diag.sys
+     * @method
+     * @returns {Promise|undefined}
+     * @memberof Api#
+     */
     sys: promisify((opts, callback) => {
       if (typeof (opts) === 'function') {
         callback = opts
@@ -26,6 +39,13 @@ module.exports = (send) => {
         qs: opts
       }, callback)
     }),
+
+    /**
+     * @alias diag.cmds
+     * @method
+     * @returns {Promise|undefined}
+     * @memberof Api#
+     */
     cmds: promisify((opts, callback) => {
       if (typeof (opts) === 'function') {
         callback = opts