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

@@ -32,3 +32,4 @@ build
 node_modules
 
 test
+docs

documentation.yml

@@ -0,0 +1,3 @@
+toc:
+  - name: Intro
+    file: intro.md

intro.md

@@ -0,0 +1,54 @@
+## Install
+
+### npm
+
+This project is available through [npm](https://www.npmjs.com/). To install:
+
+```bash
+$ npm install ipfs --save
+```
+
+Requires npm@3 and node >= 4, tested on OSX & Linux, expected to work on Windows.
+
+### Use in Node.js
+
+To include this project programmatically:
+
+```js
+var IPFS = require('ipfs')
+
+var node = new IPFS()
+```
+
+### Through command line tool
+
+In order to use js-ipfs as a CLI, you must install it with the `global` flag. Run the following (even if you have ipfs installed locally):
+
+```bash
+$ npm install ipfs --global
+```
+
+The CLI is available by using the command `jsipfs` in your terminal. This is aliased, instead of using `ipfs`, to make sure it does not conflict with the Go implementation.
+
+### Use in the browser with browserify, webpack or any bundler
+
+The code published to npm that gets loaded on require is in fact a ES5 transpiled version with the right shims added. This means that you can require it and use with your favourite bundler without having to adjust the asset management process.
+
+```js
+var ipfs = require('ipfs');
+```
+
+### Use in a browser using a script tag
+
+Loading this module in a browser (using a `<script>` tag) makes the `Ipfs` object available in the global namespace.
+
+The last published version of the package become [available for download](https://unpkg.com/ipfs/dist/) from [unpkg](https://unpkg.com/) and thus you may use it as the source:
+
+
+```html
+<!-- loading the minified version -->
+<script src="https://unpkg.com/ipfs/dist/index.min.js"></script>
+
+<!-- loading the human-readable (not minified) version -->
+<script src="https://unpkg.com/ipfs/dist/index.js"></script>
+```

package.json

@@ -20,16 +20,17 @@
   "scripts": {
     "lint": "aegir-lint",
     "coverage": "gulp coverage",
+    "docs": "aegir-docs",
     "test": "gulp test",
     "test:node": "gulp test:node",
     "test:node:core": "TEST=core npm run test:node",
     "test:node:http": "TEST=http npm run test:node",
     "test:node:cli": "TEST=cli npm run test:node",
     "test:browser": "gulp test:browser",
     "build": "gulp build",
-    "release": "gulp release",
-    "release-minor": "gulp release --type minor",
-    "release-major": "gulp release --type major",
+    "release": "gulp release --docs",
+    "release-minor": "gulp release --type minor --docs",
+    "release-major": "gulp release --type major --docs",
     "coverage-publish": "aegir-coverage publish"
   },
   "pre-commit": [
@@ -150,4 +151,4 @@
     "nginnever <[email protected]>",
     "npmcdn-to-unpkg-bot <[email protected]>"
   ]
-}
+}

src/core/components/bitswap.js

@@ -8,6 +8,12 @@ function formatWantlist (list) {
 
 module.exports = function bitswap (self) {
   return {
+    /**
+     * @alias bitswap.wantlist
+     * @memberof IPFS#
+     * @method
+     * @returns {Array}
+     */
     wantlist: () => {
       if (!self.isOnline()) {
         throw OFFLINE_ERROR
@@ -16,6 +22,12 @@ module.exports = function bitswap (self) {
       const list = self._bitswap.getWantlist()
       return formatWantlist(list)
     },
+    /**
+     * @alias bitswap.stat
+     * @memberof IPFS#
+     * @method
+     * @returns {Object}
+     */
     stat: () => {
       if (!self.isOnline()) {
         throw OFFLINE_ERROR
@@ -27,6 +39,14 @@ module.exports = function bitswap (self) {
 
       return stats
     },
+    /**
+     * NOT IMPLEMENTED
+     * @alias bitswap.unwant
+     * @memberof IPFS#
+     * @method
+     * @param {*} key
+     * @returns {undefined}
+     */
     unwant: (key) => {
       if (!self.isOnline()) {
         throw OFFLINE_ERROR

src/core/components/block.js

@@ -7,10 +7,24 @@ const waterfall = require('async/waterfall')
 
 module.exports = function block (self) {
   return {
+    /**
+     * @alias block.get
+     * @memberof IPFS#
+     * @method
+     * @param {function(Error)} callback
+     * @returns {undefined}
+     */
     get: (cid, callback) => {
       cid = cleanCid(cid)
       self._blockService.get(cid, callback)
     },
+    /**
+     * @alias block.put
+     * @memberof IPFS#
+     * @method
+     * @param {function(Error)} callback
+     * @returns {undefined}
+     */
     put: (block, cid, callback) => {
       if (typeof cid === 'function') {
         // legacy (without CID)
@@ -49,10 +63,24 @@ module.exports = function block (self) {
         callback(null, block)
       })
     },
+    /**
+     * @alias block.rm
+     * @memberof IPFS#
+     * @method
+     * @param {function(Error)} callback
+     * @returns {undefined}
+     */
     rm: (cid, callback) => {
       cid = cleanCid(cid)
       self._blockService.delete(cid, callback)
     },
+    /**
+     * @alias block.stat
+     * @memberof IPFS#
+     * @method
+     * @param {function(Error)} callback
+     * @returns {undefined}
+     */
     stat: (cid, callback) => {
       cid = cleanCid(cid)
 

src/core/components/bootstrap.js

@@ -2,6 +2,12 @@
 
 module.exports = function bootstrap (self) {
   return {
+    /**
+     * @alias bootstrap.list
+     * @memberof IPFS#
+     * @param {function(Error, Array<string>)} callback
+     * @returns {Promise<Array<string>>|undefined}
+     */
     list: (callback) => {
       self._repo.config.get((err, config) => {
         if (err) {
@@ -10,6 +16,14 @@ module.exports = function bootstrap (self) {
         callback(null, config.Bootstrap)
       })
     },
+
+    /**
+     * @alias bootstrap.add
+     * @memberof IPFS#
+     * @param {string} multiaddr
+     * @param {function(Error)} callback
+     * @returns {Promise<undefined>|undefined}
+     */
     add: (multiaddr, callback) => {
       self._repo.config.get((err, config) => {
         if (err) {
@@ -19,6 +33,14 @@ module.exports = function bootstrap (self) {
         self._repo.config.set(config, callback)
       })
     },
+
+    /**
+     * @alias bootstrap.rm
+     * @memberof IPFS#
+     * @param {string} multiaddr
+     * @param {function(Error)} callback
+     * @returns {Promise<undefiend>|undefined}
+     */
     rm: (multiaddr, callback) => {
       self._repo.config.get((err, config) => {
         if (err) {

src/core/components/config.js

@@ -7,6 +7,13 @@ const _set = require('lodash.set')
 
 module.exports = function config (self) {
   return {
+    /**
+     * @alias config.get
+     * @memberof IPFS#
+     * @method
+     * @param {function(Error)} callback
+     * @returns {Promise<undefined>|undefined}
+     */
     get: promisify((key, callback) => {
       if (typeof key === 'function') {
         callback = key
@@ -33,6 +40,13 @@ module.exports = function config (self) {
         }
       })
     }),
+    /**
+     * @alias config.set
+     * @memberof IPFS#
+     * @method
+     * @param {function(Error)} callback
+     * @returns {Promise<undefined>|undefined}
+     */
     set: promisify((key, value, callback) => {
       if (!key || typeof key !== 'string') {
         return callback(new Error('Invalid key type'))
@@ -50,6 +64,13 @@ module.exports = function config (self) {
         self.config.replace(config, callback)
       })
     }),
+    /**
+     * @alias config.replace
+     * @memberof IPFS#
+     * @method
+     * @param {function(Error)} callback
+     * @returns {Promise<undefined>|undefined}
+     */
     replace: promisify((config, callback) => {
       self._repo.config.set(config, callback)
     })

src/core/components/files.js

@@ -25,12 +25,32 @@ module.exports = function files (self) {
   }
 
   return {
+    /**
+     * @alias files.createAddStream
+     * @memberof IPFS#
+     * @method
+     * @param {function(Error, DuplexStream)} callback
+     * @returns {Promise<DuplexStream>|undefined}
+     */
     createAddStream: (callback) => {
       callback(null, toStream(createAddPullStream()))
     },
-
+    /**
+     * @alias files.createAddPullStream
+     * @memberof IPFS#
+     * @method
+     * @param {function(Error, Pullstream)} callback
+     * @returns {Promise<PullStream>|undefined}
+     */
     createAddPullStream: createAddPullStream,
-
+    /**
+     * @alias files.add
+     * @memberof IPFS#
+     * @method
+     * @param {*} data
+     * @param {function(Error *)} callback
+     * @returns {Promise<*>|undefined}
+     */
     add: promisify((data, callback) => {
       if (!callback || typeof callback !== 'function') {
         callback = noop
@@ -48,7 +68,14 @@ module.exports = function files (self) {
         pull.collect(callback)
       )
     }),
-
+    /**
+     * @alias files.cat
+     * @memberof IPFS#
+     * @method
+     * @param {string} hash
+     * @param {function(Error, ReadableStream)} callback
+     * @returns {Promise<ReadableStream>|undefined}
+     */
     cat: promisify((hash, callback) => {
       if (typeof hash === 'function') {
         return callback(new Error('You must supply a multihash'))
@@ -77,7 +104,14 @@ module.exports = function files (self) {
         )
       })
     }),
-
+    /**
+     * @alias files.get
+     * @memberof IPFS#
+     * @method
+     * @param {string} hash
+     * @param {function(Error, *)} callback
+     * @returns {Promise<*>|undefined}
+     */
     get: promisify((hash, callback) => {
       callback(null, toStream.source(pull(
         exporter(hash, self._ipldResolver),
@@ -91,7 +125,14 @@ module.exports = function files (self) {
         })
       )))
     }),
-
+    /**
+     * @alias files.getPull
+     * @memberof IPFS#
+     * @method
+     * @param {string} hash
+     * @param {function(Error, *)} callback
+     * @returns {Promise<*>|undefined}
+     */
     getPull: promisify((hash, callback) => {
       callback(null, exporter(hash, self._ipldResolver))
     })