docs(api): more

Author: dignifiedquire

src/api/add.js

@@ -10,9 +10,9 @@ module.exports = (send) => {
    *
    * @alias add
    * @method
-   * @param {(Buffer|Stream|Array)} files - The content to add.
-   * @param {function=} callback
-   * @returns {Promise}
+   * @param {(Buffer|Stream|Array<Buffer|Stream>)} files - The content to add.
+   * @param {function(Error, {hash: string})} [callback]
+   * @returns {Promise<{hash: string}>|undefined}
    *
    * @memberof Api#
    *

src/api/bitswap.js

@@ -7,53 +7,57 @@ module.exports = (send) => {
     /**
      * Show blocks currently on the wantlist.
      *
+     * Print out all blocks currently on the bitswap wantlist for the local peer.
+     *
      * @alias bitswap.wantlist
      * @method
-     * @param {Function} [callback]
+     * @param {function(Error, Array<string>)} [callback]
      *
-     * @returns {Promise}
+     * @returns {Promise<Array<string>>|undefined}
      * @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]
+     * @param {function(Error, Object)} [callback]
      *
-     * @returns {Promise}
+     * @returns {Promise<Object>|undefined}
      * @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]
+     * @param {string|Array<string>} key - The `base58` encoded multihashes of the blocks to unwant.
+     * @param {Object} [opts={}]
+     * @param {function(Error)} [callback]
      *
-     * @returns {Promise}
+     * @returns {Promise<undefined>|undefined}
      * @memberof Api#
      */
-    unwant: promisify((args, opts, callback) => {
+    unwant: promisify((key, opts, callback) => {
       if (typeof (opts) === 'function') {
         callback = opts
         opts = {}
       }
       send({
         path: 'bitswap/unwant',
-        args: args,
+        args: key,
         qs: opts
       }, callback)
     })

src/api/block.js

@@ -9,9 +9,14 @@ const CID = require('cids')
 module.exports = (send) => {
   return {
     /**
+     * Get a raw IPFS block
+     *
      * @alias block.get
      * @method
-     * @returns {Promise|undefined}
+     * @param {CID|string} args - the multihash or CID of the block.
+     * @param {Object} [opts={}]
+     * @param {function(Error, Block)} [callback]
+     * @returns {Promise<Block>|undefined}
      * @memberof Api#
      */
     get: promisify((args, opts, callback) => {
@@ -46,15 +51,20 @@ module.exports = (send) => {
     }),
 
     /**
+     * Print information of a raw IPFS block.
+     *
      * @alias block.stat
      * @method
-     * @returns {Promise|undefined}
+     * @param {CID|string} key - the `base58` multihash or CID of the block.
+     * @param {Object} [opts={}]
+     * @param {function(Error, {key: string, size: string})} [callback]
+     * @returns {Promise<{key: string, size: string}>|undefined}
      * @memberof Api#
      */
-    stat: promisify((args, opts, callback) => {
+    stat: promisify((key, opts, callback) => {
       // TODO this needs to be adjusted with the new go-ipfs http-api
-      if (args && CID.isCID(args)) {
-        args = multihash.toB58String(args.multihash)
+      if (key && CID.isCID(key)) {
+        key = multihash.toB58String(key.multihash)
       }
 
       if (typeof (opts) === 'function') {
@@ -63,7 +73,7 @@ module.exports = (send) => {
       }
       return send({
         path: 'block/stat',
-        args: args,
+        args: key,
         qs: opts
       }, (err, stats) => {
         if (err) {
@@ -77,9 +87,15 @@ module.exports = (send) => {
     }),
 
     /**
+     * Store input as an IPFS block.
+     *
      * @alias block.put
      * @method
-     * @returns {Promise|undefined}
+     * @param {Object} block - The block to create.
+     * @param {Buffer} block.data -  The data to be stored as an IPFS block.
+     * @param {CID} [cid]
+     * @param {function(Error, Block)} [callback]
+     * @returns {Promise<Block>|undefined}
      * @memberof Api#
      */
     put: promisify((block, cid, callback) => {

src/api/bootstrap.js

@@ -5,12 +5,16 @@ const promisify = require('promisify-es6')
 module.exports = (send) => {
   return {
     /**
+     * Add peers to the bootstrap list.
      * @alias bootstrap.add
      * @method
-     * @returns {Promise|undefined}
+     * @param {string|Array<string>} peers - A list of peers to add to the bootstrap list (in the format `'<multiaddr>/<peerID>'`)
+     * @param {Object} [opts={}]
+     * @param {function(Error)} [callback]
+     * @returns {Promise<undefined>|undefined}
      * @memberof Api#
      */
-    add: promisify((args, opts, callback) => {
+    add: promisify((peers, opts, callback) => {
       if (typeof opts === 'function' &&
           !callback) {
         callback = opts
@@ -25,25 +29,30 @@ module.exports = (send) => {
         opts = {}
       }
 
-      if (args && typeof args === 'object') {
-        opts = args
-        args = undefined
+      if (peers && typeof peers === 'object') {
+        opts = peers
+        peers = undefined
       }
 
       send({
         path: 'bootstrap/add',
-        args: args,
+        args: peers,
         qs: opts
       }, callback)
     }),
 
     /**
+     * Remove peers from the bootstrap list.
+     *
      * @alias bootstrap.rm
      * @method
-     * @returns {Promise|undefined}
+     * @param {string|Array<string>} peers - The peers to remove from the bootstrap list
+     * @param {Object} [opts={}]
+     * @param {function(Error)} [callback]
+     * @returns {Promise<undefined>|undefined}
      * @memberof Api#
      */
-    rm: promisify((args, opts, callback) => {
+    rm: promisify((peers, opts, callback) => {
       if (typeof opts === 'function' &&
           !callback) {
         callback = opts
@@ -58,22 +67,26 @@ module.exports = (send) => {
         opts = {}
       }
 
-      if (args && typeof args === 'object') {
-        opts = args
-        args = undefined
+      if (peers && typeof peers === 'object') {
+        opts = peers
+        peers = undefined
       }
 
       send({
         path: 'bootstrap/rm',
-        args: args,
+        args: peers,
         qs: opts
       }, callback)
     }),
 
     /**
+     * Show peers in the bootstrap list.
+     *
      * @alias bootstrap.list
      * @method
-     * @returns {Promise|undefined}
+     * @param {Object} [opts={}]
+     * @param {function(Error, Array<string>)} [callback]
+     * @returns {Promise<Array<string>|undefined}
      * @memberof Api#
      */
     list: promisify((opts, callback) => {