docs(api): first pass

As `loadash.contains` is deprecated.

.gitignore

@@ -25,3 +25,5 @@ build/Release
 # Dependency directory
 # https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git
 node_modules
+
+docs

.npmignore

@@ -27,3 +27,4 @@ build/Release
 node_modules
 
 test
+docs

package.json

@@ -6,9 +6,10 @@
   "scripts": {
     "lint": "aegir-lint",
     "test": "aegir-test --env node",
-    "release": "aegir-release --env no-build",
+    "docs": "aegir-docs",
-    "release-minor": "aegir-release --type minor --env no-build",
+    "release": "aegir-release --env no-build --docs",
-    "release-major": "aegir-release --type major --env no-build",
+    "release-minor": "aegir-release --type minor --env no-build --docs",
+    "release-major": "aegir-release --type major --env no-build --docs",
     "coverage": "aegir-coverage",
     "coverage-publish": "aegir-coverage publish"
   },
@@ -33,20 +34,20 @@
     "node": ">=4.0.0"
   },
   "devDependencies": {
-    "aegir": "^9.0.1",
+    "aegir": "^9.2.0",
     "chai": "^3.5.0",
     "interface-transport": "^0.3.3",
     "lodash.isfunction": "^3.0.8",
-    "pre-commit": "^1.1.2",
+    "pre-commit": "^1.1.3",
-    "pull-stream": "^3.4.5"
+    "pull-stream": "^3.5.0"
   },
   "dependencies": {
     "interface-connection": "0.3.0",
-    "ip-address": "^5.8.0",
+    "ip-address": "^5.8.2",
-    "lodash.contains": "^2.4.3",
+    "lodash.includes": "^4.3.0",
     "mafmt": "^2.1.2",
-    "multiaddr": "^2.0.3",
+    "multiaddr": "^2.1.1",
-    "stream-to-pull-stream": "^1.7.0"
+    "stream-to-pull-stream": "^1.7.2"
   },
   "contributors": [
     "David Dias <daviddias.p@gmail.com>",

src/index.js

@@ -3,7 +3,7 @@
 const net = require('net')
 const toPull = require('stream-to-pull-stream')
 const mafmt = require('mafmt')
-const contains = require('lodash.contains')
+const includes = require('lodash.includes')
 const isFunction = require('lodash.isfunction')
 const Connection = require('interface-connection').Connection
 const debug = require('debug')
@@ -11,21 +11,32 @@ const log = debug('libp2p:tcp:dial')
 
 const createListener = require('./listener')
 
-module.exports = class TCP {
+/**
-  dial (ma, options, cb) {
+ *
+ */
+class TCP {
+  /**
+   * Dial to another peer.
+   *
+   * @param {Multiaddr} ma - The address of the peer we want to dial to.
+   * @param {Object} [options={}]
+   * @param {function(Error?, Array<Multiaddr>?)} [callback]
+   * @returns {Connection}
+   */
+  dial (ma, options, callback) {
     if (isFunction(options)) {
-      cb = options
+      callback = options
       options = {}
     }
 
-    if (!cb) {
+    if (!callback) {
-      cb = () => {}
+      callback = () => {}
     }
 
     const cOpts = ma.toOptions()
     log('Connecting to %s %s', cOpts.port, cOpts.host)
 
-    const rawSocket = net.connect(cOpts, cb)
+    const rawSocket = net.connect(cOpts, callback)
 
     rawSocket.once('timeout', () => {
       log('timeout')
@@ -43,6 +54,13 @@ module.exports = class TCP {
     return conn
   }
 
+  /**
+   * Listen for incoming `TCP` connetions.
+   *
+   * @param {Object} [options={}]
+   * @param {function(Connection)} [handler] - Called with newly incomin connections.
+   * @returns {Listener}
+   */
   createListener (options, handler) {
     if (isFunction(options)) {
       handler = options
@@ -54,15 +72,24 @@ module.exports = class TCP {
     return createListener(handler)
   }
 
+  /**
+   * Filter a list of multiaddrs for those which contain
+   * valid `TCP` addresses.
+   *
+   * @param {Multiaddr|Array<Multiaddr>} multiaddrs
+   * @returns {Array<Multiaddr>}
+   */
   filter (multiaddrs) {
     if (!Array.isArray(multiaddrs)) {
       multiaddrs = [multiaddrs]
     }
     return multiaddrs.filter((ma) => {
-      if (contains(ma.protoNames(), 'ipfs')) {
+      if (includes(ma.protoNames(), 'ipfs')) {
         ma = ma.decapsulate('ipfs')
       }
       return mafmt.TCP.matches(ma)
     })
   }
 }
+
+module.exports = TCP

src/listener.js

@@ -3,7 +3,7 @@
 const multiaddr = require('multiaddr')
 const Connection = require('interface-connection').Connection
 const os = require('os')
-const contains = require('lodash.contains')
+const includes = require('lodash.includes')
 const net = require('net')
 const toPull = require('stream-to-pull-stream')
 const EventEmitter = require('events').EventEmitter
@@ -15,7 +15,49 @@ const getMultiaddr = require('./get-multiaddr')
 const IPFS_CODE = 421
 const CLOSE_TIMEOUT = 2000
 
+/**
+ * Listening for incoming connections.
+ *
+ * @event listening
+ * @instance
+ * @memberof Listener
+ */
+
+/**
+ * The server closes.
+ *
+ * @event close
+ * @instance
+ * @memberof Listener
+ */
+
+/**
+ * New connection established.
+ *
+ * @event connection
+ * @instance
+ * @type {Connection}
+ * @memberof Listener
+ */
+
+/**
+ * The underlying server encountered an error.
+ *
+ * @event error
+ * @instance
+ * @type {Error}
+ * @memberof Listener
+ */
+
 module.exports = (handler) => {
+  /**
+   * @alias Listener
+   * @type {Eventemitter}
+   * @fires Listener#listening
+   * @fires Listener#close
+   * @fires Listener#connection
+   * @fires Listener#error
+   */
   const listener = new EventEmitter()
 
   const server = net.createServer((socket) => {
@@ -78,7 +120,7 @@ module.exports = (handler) => {
 
   listener.listen = (ma, cb) => {
     listeningAddr = ma
-    if (contains(ma.protoNames(), 'ipfs')) {
+    if (includes(ma.protoNames(), 'ipfs')) {
       ipfsId = getIpfsId(ma)
       listeningAddr = ma.decapsulate('ipfs')
     }