diff --git a/.gitignore b/.gitignore
index 254988dc81..9b8257ccfe 100644
--- a/.gitignore
+++ b/.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
\ No newline at end of file
diff --git a/.npmignore b/.npmignore
index 59335fda64..f6c52f551d 100644
--- a/.npmignore
+++ b/.npmignore
@@ -32,3 +32,4 @@ build
node_modules
test
+docs
\ No newline at end of file
diff --git a/documentation.yml b/documentation.yml
new file mode 100644
index 0000000000..580d1f3151
--- /dev/null
+++ b/documentation.yml
@@ -0,0 +1,3 @@
+toc:
+ - name: Intro
+ file: intro.md
diff --git a/intro.md b/intro.md
new file mode 100644
index 0000000000..c4ab79d5e9
--- /dev/null
+++ b/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 `
+
+
+
+```
diff --git a/package.json b/package.json
index 797d5a7eff..a256cf7c5c 100644
--- a/package.json
+++ b/package.json
@@ -20,6 +20,7 @@
"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",
@@ -27,9 +28,9 @@
"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 ",
"npmcdn-to-unpkg-bot "
]
-}
\ No newline at end of file
+}
diff --git a/src/core/components/bitswap.js b/src/core/components/bitswap.js
index c8b7e1a806..9435144c1b 100644
--- a/src/core/components/bitswap.js
+++ b/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
diff --git a/src/core/components/block.js b/src/core/components/block.js
index 2ec08a5561..7952ff098f 100644
--- a/src/core/components/block.js
+++ b/src/core/components/block.js
@@ -7,10 +7,31 @@ const waterfall = require('async/waterfall')
module.exports = function block (self) {
return {
+ /**
+ * @alias block.get
+ * @memberof IPFS#
+ * @method
+ * @param {CID} cid
+ * @param {function(Error)} callback
+ * @returns {undefined}
+ *
+ * @see https://github.com/ipfs/interface-ipfs-core/tree/master/API/block#get
+ */
get: (cid, callback) => {
cid = cleanCid(cid)
self._blockService.get(cid, callback)
},
+ /**
+ * @alias block.put
+ * @memberof IPFS#
+ * @method
+ * @param {Block} block
+ * @param {CID} cid
+ * @param {function(Error)} callback
+ * @returns {undefined}
+ *
+ * @see https://github.com/ipfs/interface-ipfs-core/tree/master/API/block#put
+ */
put: (block, cid, callback) => {
if (typeof cid === 'function') {
// legacy (without CID)
@@ -49,10 +70,30 @@ module.exports = function block (self) {
callback(null, block)
})
},
+ /**
+ * @alias block.rm
+ * @memberof IPFS#
+ * @method
+ * @param {CID} cid
+ * @param {function(Error)} callback
+ * @returns {undefined}
+ *
+ * @see https://github.com/ipfs/interface-ipfs-core/tree/master/API/block#rm
+ */
rm: (cid, callback) => {
cid = cleanCid(cid)
self._blockService.delete(cid, callback)
},
+ /**
+ * @alias block.stat
+ * @memberof IPFS#
+ * @method
+ * @param {CID} cid
+ * @param {function(Error)} callback
+ * @returns {undefined}
+ *
+ * @see https://github.com/ipfs/interface-ipfs-core/tree/master/API/block#stat
+ */
stat: (cid, callback) => {
cid = cleanCid(cid)
diff --git a/src/core/components/bootstrap.js b/src/core/components/bootstrap.js
index b83eead83e..6c536c29e3 100644
--- a/src/core/components/bootstrap.js
+++ b/src/core/components/bootstrap.js
@@ -2,6 +2,12 @@
module.exports = function bootstrap (self) {
return {
+ /**
+ * @alias bootstrap.list
+ * @memberof IPFS#
+ * @param {function(Error, Array)} callback
+ * @returns {Promise>|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}
+ */
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|undefined}
+ */
rm: (multiaddr, callback) => {
self._repo.config.get((err, config) => {
if (err) {
diff --git a/src/core/components/config.js b/src/core/components/config.js
index 4fa5ec1189..b717471a3e 100644
--- a/src/core/components/config.js
+++ b/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}
+ */
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}
+ */
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}
+ */
replace: promisify((config, callback) => {
self._repo.config.set(config, callback)
})
diff --git a/src/core/components/files.js b/src/core/components/files.js
index 639677c0a7..f30234d4e9 100644
--- a/src/core/components/files.js
+++ b/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|undefined}
+ */
createAddStream: (callback) => {
callback(null, toStream(createAddPullStream()))
},
-
+ /**
+ * @alias files.createAddPullStream
+ * @memberof IPFS#
+ * @method
+ * @param {function(Error, Pullstream)} callback
+ * @returns {Promise|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|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))
})
diff --git a/src/core/components/go-offline.js b/src/core/components/go-offline.js
index 0c5d084c0e..ffc61d1784 100644
--- a/src/core/components/go-offline.js
+++ b/src/core/components/go-offline.js
@@ -1,6 +1,13 @@
'use strict'
module.exports = function goOffline (self) {
+ /**
+ * @alias goOffline
+ * @memberof IPFS#
+ * @method
+ * @param {function(Error)} cb
+ * @returns {undefined}
+ */
return (cb) => {
self._blockService.goOffline()
self._bitswap.stop()
diff --git a/src/core/components/go-online.js b/src/core/components/go-online.js
index 793a0269a5..a3109872ac 100644
--- a/src/core/components/go-online.js
+++ b/src/core/components/go-online.js
@@ -4,6 +4,13 @@ const series = require('async/series')
const Bitswap = require('ipfs-bitswap')
module.exports = function goOnline (self) {
+ /**
+ * @alias goOnline
+ * @memberof IPFS#
+ * @method
+ * @param {function(Error)} cb
+ * @returns {undefined}
+ */
return (cb) => {
series([
self.load,
diff --git a/src/core/components/id.js b/src/core/components/id.js
index 8e8485eda0..f6d2e9baa3 100644
--- a/src/core/components/id.js
+++ b/src/core/components/id.js
@@ -3,6 +3,17 @@
const promisify = require('promisify-es6')
module.exports = function id (self) {
+ /**
+ * @alias id
+ * @memberof IPFS#
+ * @method
+ * @method
+ * @param {Object} [opts={}]
+ * @param {function(Error, IPFS#Id)} callback
+ * @returns {Promise|undefined}
+ *
+ * @see https://github.com/ipfs/interface-ipfs-core/tree/master/API/generic#id
+ */
return promisify((opts, callback) => {
if (typeof opts === 'function') {
callback = opts
@@ -28,3 +39,13 @@ module.exports = function id (self) {
}
})
}
+
+/**
+ * @typedef {object} Id
+ * @memberof IPFS#
+ * @param {string} id - encoded in `base58`
+ * @param {string} publicKey - encoded in `base64`
+ * @param {Array} addresses
+ * @param {string} agentVersion
+ * @param {string} protocolVersion
+ */
diff --git a/src/core/components/init.js b/src/core/components/init.js
index a2081984ec..5f492650d4 100644
--- a/src/core/components/init.js
+++ b/src/core/components/init.js
@@ -9,6 +9,17 @@ const addDefaultAssets = require('./init-assets')
const VERSION = '3'
module.exports = function init (self) {
+ /**
+ * @alias init
+ * @memberof IPFS#
+ * @method
+ * @param {Object} opts
+ * @param {boolean} opts.emptyRepo
+ * @param {number} [opts.bits=2048]
+ * @param {function(string)} opts.log
+ * @param {function(Error)} callback
+ * @returns {undefined}
+ */
return (opts, callback) => {
if (typeof opts === 'function') {
callback = opts
diff --git a/src/core/components/is-online.js b/src/core/components/is-online.js
index 5c07edb4e3..1323294f9b 100644
--- a/src/core/components/is-online.js
+++ b/src/core/components/is-online.js
@@ -1,6 +1,12 @@
'use strict'
module.exports = function isOnline (self) {
+ /**
+ * @alias isOnline
+ * @memberof IPFS#
+ * @method
+ * @returns {boolean}
+ */
return () => {
return self._bitswap && self._libp2pNode
}
diff --git a/src/core/components/libp2p.js b/src/core/components/libp2p.js
index f6385992bf..34f108da61 100644
--- a/src/core/components/libp2p.js
+++ b/src/core/components/libp2p.js
@@ -6,6 +6,13 @@ const promisify = require('promisify-es6')
module.exports = function libp2p (self) {
// TODO Just expose libp2p API directly, this start stop wrapping doesn't make that much sense anymore :)
return {
+ /**
+ * @alias libp2p.start
+ * @memberof IPFS#
+ * @method
+ * @param {function(Error)} callback
+ * @returns {Promise|undefined}
+ */
start: promisify((callback) => {
self._libp2pNode = new Node(self._peerInfo)
self._libp2pNode.start((err) => {
@@ -28,6 +35,13 @@ module.exports = function libp2p (self) {
self._libp2pNode.peerBook.put(peerInfo)
})
}),
+ /**
+ * @alias libp2p.stop
+ * @memberof IPFS#
+ * @method
+ * @param {function(Error)} callback
+ * @returns {Promise|undefined}
+ */
stop: promisify((callback) => {
self._libp2pNode.stop(callback)
})
diff --git a/src/core/components/load.js b/src/core/components/load.js
index b2a7ccd239..8df9e3ed32 100644
--- a/src/core/components/load.js
+++ b/src/core/components/load.js
@@ -8,6 +8,13 @@ const waterfall = require('async/waterfall')
const utils = require('../utils')
module.exports = function load (self) {
+ /**
+ * @alias load
+ * @memberof IPFS#
+ * @method
+ * @param {function(Error)} callback
+ * @returns {undefined}
+ */
return (callback) => {
waterfall([
(cb) => utils.ifRepoExists(self._repo, cb),
diff --git a/src/core/components/object.js b/src/core/components/object.js
index 86f851798d..40c0c18426 100644
--- a/src/core/components/object.js
+++ b/src/core/components/object.js
@@ -91,6 +91,15 @@ module.exports = function object (self) {
}
return {
+ /**
+ * @alias object.new
+ * @memberof IPFS#
+ * @method
+ * @param {function(Error)} callback
+ * @returns {Promise|undefined}
+ *
+ * @see https://github.com/ipfs/interface-ipfs-core/tree/master/API/object#objectnew
+ */
new: promisify((callback) => {
DAGNode.create(new Buffer(0), (err, node) => {
if (err) {
@@ -108,6 +117,16 @@ module.exports = function object (self) {
})
})
}),
+
+ /**
+ * @alias object.put
+ * @memberof IPFS#
+ * @method
+ * @param {function(Error)} callback
+ * @returns {Promise|undefined}
+ *
+ * @see https://github.com/ipfs/interface-ipfs-core/tree/master/API/object#objectput
+ */
put: promisify((obj, options, callback) => {
if (typeof options === 'function') {
callback = options
@@ -166,6 +185,15 @@ module.exports = function object (self) {
}
}),
+ /**
+ * @alias object.get
+ * @memberof IPFS#
+ * @method
+ * @param {function(Error)} callback
+ * @returns {Promise|undefined}
+ *
+ * @see https://github.com/ipfs/interface-ipfs-core/tree/master/API/object#objectget
+ */
get: promisify((multihash, options, callback) => {
if (typeof options === 'function') {
callback = options
@@ -183,6 +211,15 @@ module.exports = function object (self) {
self._ipldResolver.get(cid, callback)
}),
+ /**
+ * @alias object.data
+ * @memberof IPFS#
+ * @method
+ * @param {function(Error)} callback
+ * @returns {Promise|undefined}
+ *
+ * @see https://github.com/ipfs/interface-ipfs-core/tree/master/API/object#objectdata
+ */
data: promisify((multihash, options, callback) => {
if (typeof options === 'function') {
callback = options
@@ -197,6 +234,15 @@ module.exports = function object (self) {
})
}),
+ /**
+ * @alias object.links
+ * @memberof IPFS#
+ * @method
+ * @param {function(Error)} callback
+ * @returns {Promise|undefined}
+ *
+ * @see https://github.com/ipfs/interface-ipfs-core/tree/master/API/object#objectlinks
+ */
links: promisify((multihash, options, callback) => {
if (typeof options === 'function') {
callback = options
@@ -212,6 +258,17 @@ module.exports = function object (self) {
})
}),
+ /**
+ * @alias object.stat
+ * @memberof IPFS#
+ * @method
+ * @param {*} multihash
+ * @param {Object} [options={}]
+ * @param {function(Error)} callback
+ * @returns {Promise|undefined}
+ *
+ * @see https://github.com/ipfs/interface-ipfs-core/tree/master/API/object#objectstat
+ */
stat: promisify((multihash, options, callback) => {
if (typeof options === 'function') {
callback = options
@@ -245,13 +302,37 @@ module.exports = function object (self) {
})
}),
- patch: promisify({
+ patch: {
+ /**
+ * @alias object.patch.addLink
+ * @memberof IPFS#
+ * @method
+ * @param {Buffer|string} multihash
+ * @param {DAGLink} link
+ * @param {Object} [options={}]
+ * @param {function(Error)} callback
+ * @returns {Promise|undefined}
+ *
+ * @see https://github.com/ipfs/interface-ipfs-core/tree/master/API/object#objectpatchaddlink
+ */
addLink (multihash, link, options, callback) {
editAndSave((node, cb) => {
DAGNode.addLink(node, link, cb)
})(multihash, options, callback)
},
+ /**
+ * @alias object.patch.rmLink
+ * @memberof IPFS#
+ * @method
+ * @param {Buffer|string} multihash
+ * @param {DAGLink} linkRef
+ * @param {Object} [options={}]
+ * @param {function(Error)} callback
+ * @returns {Promise|undefined}
+ *
+ * @see https://github.com/ipfs/interface-ipfs-core/tree/master/API/object#objectpatchrmlink
+ */
rmLink (multihash, linkRef, options, callback) {
editAndSave((node, cb) => {
if (linkRef.constructor &&
@@ -262,6 +343,18 @@ module.exports = function object (self) {
})(multihash, options, callback)
},
+ /**
+ * @alias object.patch.appendData
+ * @memberof IPFS#
+ * @method
+ * @param {Buffer|string} multihash
+ * @param {Object} data
+ * @param {Object} [options={}]
+ * @param {function(Error)} callback
+ * @returns {Promise|undefined}
+ *
+ * @see https://github.com/ipfs/interface-ipfs-core/tree/master/API/object#objectpatchappenddata
+ */
appendData (multihash, data, options, callback) {
editAndSave((node, cb) => {
const newData = Buffer.concat([node.data, data])
@@ -269,11 +362,23 @@ module.exports = function object (self) {
})(multihash, options, callback)
},
+ /**
+ * @alias object.patch.setData
+ * @memberof IPFS#
+ * @method
+ * @param {Buffer|string} multihash
+ * @param {Object} data
+ * @param {Object} [options={}]
+ * @param {function(Error)} callback
+ * @returns {Promise|undefined}
+ *
+ * @see https://github.com/ipfs/interface-ipfs-core/tree/master/API/object#objectpatchsetdata
+ */
setData (multihash, data, options, callback) {
editAndSave((node, cb) => {
DAGNode.create(data, node.links, cb)
})(multihash, options, callback)
}
- })
+ }
}
}
diff --git a/src/core/components/ping.js b/src/core/components/ping.js
index eb7a45b34f..a8b78cad8a 100644
--- a/src/core/components/ping.js
+++ b/src/core/components/ping.js
@@ -3,6 +3,13 @@
const promisify = require('promisify-es6')
module.exports = function ping (self) {
+ /**
+ * @alias ping
+ * @memberof IPFS#
+ * @method
+ * @param {function(Error)} callback
+ * @returns {Promise|undefined}
+ */
return promisify((callback) => {
callback(new Error('Not implemented'))
})
diff --git a/src/core/components/swarm.js b/src/core/components/swarm.js
index 45313a79ce..891274c7a6 100644
--- a/src/core/components/swarm.js
+++ b/src/core/components/swarm.js
@@ -9,6 +9,14 @@ const OFFLINE_ERROR = require('../utils').OFFLINE_ERROR
module.exports = function swarm (self) {
return {
+ /**
+ * @alias swarm.peers
+ * @memberof IPFS#
+ * @method
+ * @param {Object} [opts={}]
+ * @param {function(Error)} callback
+ * @returns {Promise<*>|undefined}
+ */
peers: promisify((opts, callback) => {
if (typeof opts === 'function') {
callback = opts
@@ -46,7 +54,15 @@ module.exports = function swarm (self) {
callback(null, peerList)
}),
- // all the addrs we know
+ /**
+ * Get all the addresses we know.
+ *
+ * @alias swarm.addrs
+ * @memberof IPFS#
+ * @method
+ * @param {function(Error)} callback
+ * @returns {Promise<*>|undefined}
+ */
addrs: promisify((callback) => {
if (!self.isOnline()) {
return callback(OFFLINE_ERROR)
@@ -56,6 +72,14 @@ module.exports = function swarm (self) {
callback(null, peers)
}),
+ /**
+ *
+ * @alias swarm.localAddrs
+ * @memberof IPFS#
+ * @method
+ * @param {function(Error)} callback
+ * @returns {Promise<*>|undefined}
+ */
localAddrs: promisify((callback) => {
if (!self.isOnline()) {
return callback(OFFLINE_ERROR)
@@ -64,6 +88,14 @@ module.exports = function swarm (self) {
callback(null, self._libp2pNode.peerInfo.multiaddrs)
}),
+ /**
+ * @alias swarm.connect
+ * @memberof IPFS#
+ * @method
+ * @param {Multiaddr|string} maddr
+ * @param {function(Error)} callback
+ * @returns {Promise<*>|undefined}
+ */
connect: promisify((maddr, callback) => {
if (!self.isOnline()) {
return callback(OFFLINE_ERROR)
@@ -76,6 +108,14 @@ module.exports = function swarm (self) {
self._libp2pNode.dialByMultiaddr(maddr, callback)
}),
+ /**
+ * @alias swarm.disconnect
+ * @memberof IPFS#
+ * @method
+ * @param {Multiaddr|string}
+ * @param {function(Error)} callback
+ * @returns {Promise<*>|undefined}
+ */
disconnect: promisify((maddr, callback) => {
if (!self.isOnline()) {
return callback(OFFLINE_ERROR)
@@ -88,6 +128,15 @@ module.exports = function swarm (self) {
self._libp2pNode.hangUpByMultiaddr(maddr, callback)
}),
+ /**
+ * NOT IMPLEMENTED
+ *
+ * @alias swarm.filters
+ * @memberof IPFS#
+ * @method
+ * @param {function(Error)} callback
+ * @returns {Promise<*>|undefined}
+ */
filters: promisify((callback) => {
// TODO
throw new Error('Not implemented')
diff --git a/src/core/components/version.js b/src/core/components/version.js
index 1d1fcca9c5..1f0c4bc876 100644
--- a/src/core/components/version.js
+++ b/src/core/components/version.js
@@ -4,6 +4,15 @@ const pkg = require('../../../package.json')
const promisify = require('promisify-es6')
module.exports = function version (self) {
+ /**
+ * @alias version
+ * @memberof IPFS#
+ * @method
+ * @param {function(Error, IPFS#Version)} callback
+ * @returns {Promise|undefined}
+ *
+ * @see https://github.com/ipfs/interface-ipfs-core/tree/master/API/generic#id
+ */
return promisify((opts, callback) => {
if (typeof opts === 'function') {
callback = opts
@@ -17,3 +26,11 @@ module.exports = function version (self) {
})
})
}
+
+/**
+ * @memberof IPFS#
+ * @typedef {Object} Version
+ * @param {string} version
+ * @param {string} repo
+ * @param {string} commit
+ */
diff --git a/src/core/index.js b/src/core/index.js
index a58836c10c..ba8c094cf0 100644
--- a/src/core/index.js
+++ b/src/core/index.js
@@ -24,47 +24,81 @@ const ping = require('./components/ping')
const files = require('./components/files')
const bitswap = require('./components/bitswap')
-exports = module.exports = IPFS
-
-function IPFS (repoInstance) {
- if (!(this instanceof IPFS)) {
- throw new Error('Must be instantiated with new')
- }
-
- if (typeof repoInstance === 'string' ||
- repoInstance === undefined) {
- repoInstance = defaultRepo(repoInstance)
- }
+/**
+ * The core IPFS component.
+ *
+ * @example
+ * const IPFS = require('ipfs')
+ * // IPFS will need a repo, it can create one for you or you can pass
+ * // it a repo instance of the type IPFS Repo
+ * // https://github.com/ipfs/js-ipfs-repo
+ * const repo = ipfsRepoOrPath
+ *
+ * // Create the IPFS node instance
+ * const node = new IPFS(repo)
+ *
+ * // We need to init our repo, in this case the repo was empty
+ * // We are picking 2048 bits for the RSA key that will be our PeerId
+ * node.init({ emptyRepo: true, bits: 2048 }, (err) => {
+ * if (err) { throw err }
+ *
+ * // Once the repo is initiated, we have to load it so that the IPFS
+ * // instance has its config values. This is useful when you have
+ * // previous created repos and you don't need to generate a new one
+ * node.load((err) => {
+ * if (err) { throw err }
+ *
+ * // Last but not the least, we want our IPFS node to use its peer
+ * // connections to fetch and serve blocks from.
+ * node.goOnline((err) => {
+ * if (err) { throw err }
+ * // Here you should be good to go and call any IPFS function
+ * })
+ * })
+ *
+ */
+class IPFS {
+ /**
+ * @param {string|IpfsRepo} repoInstance
+ */
+ constructor (repoInstance) {
+ if (typeof repoInstance === 'string' ||
+ repoInstance === undefined) {
+ repoInstance = defaultRepo(repoInstance)
+ }
- // IPFS Core Internals
- this._repo = repoInstance
- this._peerInfoBook = new PeerBook()
- this._peerInfo = null
- this._libp2pNode = null
- this._bitswap = null
- this._blockService = new BlockService(this._repo)
- this._ipldResolver = new IPLDResolver(this._blockService)
+ // IPFS Core Internals
+ this._repo = repoInstance
+ this._peerInfoBook = new PeerBook()
+ this._peerInfo = null
+ this._libp2pNode = null
+ this._bitswap = null
+ this._blockService = new BlockService(this._repo)
+ this._ipldResolver = new IPLDResolver(this._blockService)
- // IPFS Core exposed components
+ // IPFS Core exposed components
- // for booting up a node
- this.goOnline = goOnline(this)
- this.goOffline = goOffline(this)
- this.isOnline = isOnline(this)
- this.load = load(this)
- this.init = init(this)
+ // for booting up a node
+ this.goOnline = goOnline(this)
+ this.goOffline = goOffline(this)
+ this.isOnline = isOnline(this)
+ this.load = load(this)
+ this.init = init(this)
- // interface-ipfs-core defined API
- this.version = version(this)
- this.id = id(this)
- this.repo = repo(this)
- this.bootstrap = bootstrap(this)
- this.config = config(this)
- this.block = block(this)
- this.object = object(this)
- this.libp2p = libp2p(this)
- this.swarm = swarm(this)
- this.files = files(this)
- this.bitswap = bitswap(this)
- this.ping = ping(this)
+ // interface-ipfs-core defined API
+ this.version = version(this)
+ this.id = id(this)
+ this.repo = repo(this)
+ this.bootstrap = bootstrap(this)
+ this.config = config(this)
+ this.block = block(this)
+ this.object = object(this)
+ this.libp2p = libp2p(this)
+ this.swarm = swarm(this)
+ this.files = files(this)
+ this.bitswap = bitswap(this)
+ this.ping = ping(this)
+ }
}
+
+exports = module.exports = IPFS