From 2da23f637aa813a45583e36c50ffcdf5347650cf Mon Sep 17 00:00:00 2001
From: Friedel Ziegelmayer <dignifiedquire@gmail.com>
Date: Mon, 5 Dec 2016 21:38:26 +0100
Subject: [PATCH] docs: start api documentation

---
 .gitignore        |  1 +
 .npmignore        |  1 +
 documentation.yml |  1 +
 src/index.js      | 85 ++++++++++++++++++++++++++++++++++++++++++-----
 4 files changed, 79 insertions(+), 9 deletions(-)
 create mode 100644 documentation.yml

diff --git a/.gitignore b/.gitignore
index 907c78a..6b9f154 100644
--- a/.gitignore
+++ b/.gitignore
@@ -27,3 +27,4 @@ build/Release
 node_modules
 
 dist
+docs
\ No newline at end of file
diff --git a/.npmignore b/.npmignore
index 9e7af1f..4a47bf8 100644
--- a/.npmignore
+++ b/.npmignore
@@ -26,3 +26,4 @@ build/Release
 .node_repl_history
 
 test
+docs
diff --git a/documentation.yml b/documentation.yml
new file mode 100644
index 0000000..8b13789
--- /dev/null
+++ b/documentation.yml
@@ -0,0 +1 @@
+
diff --git a/src/index.js b/src/index.js
index e735f93..b7fdc74 100644
--- a/src/index.js
+++ b/src/index.js
@@ -14,7 +14,12 @@ function ensureMultiaddr (addr) {
   return multiaddr(addr)
 }
 
-// Peer represents a peer on the IPFS network
+/**
+ * Creates a new `PeerInfo` instance from an existing `PeerID`.
+ * @class {PeerInfo}
+ * @param {PeerId} peerId
+ * @returns {PeerInfo}
+ */
 function PeerInfo (peerId) {
   if (!(this instanceof PeerInfo)) {
     return new PeerInfo(peerId)
@@ -24,13 +29,41 @@ function PeerInfo (peerId) {
     throw new Error('Missing peerId. Use Peer.create(cb) to create one')
   }
 
+  /**
+   * The `PeerId` identifying this `PeerInfo`.
+   *
+   * @type {PeerId}
+   */
   this.id = peerId
 
+  /**
+   * A list of `Multiaddr`s that this `peer` can be reached at.
+   *
+   * @type {Array<Multiaddr>}
+   */
   this.multiaddrs = []
   const observedMultiaddrs = []
 
+  /**
+   *
+   * @returns {Array<Array<mixed>>}
+   */
+  this.distinctMultiaddr = () => {
+    var result = uniqBy(this.multiaddrs, function (item) {
+      return [item.toOptions().port, item.toOptions().transport].join()
+    })
+    return result
+  }
+
   this.multiaddr = {}
 
+  /**
+   * Adds a new multiaddress that `peer` can be reached at.
+   * @param {Multiaddr} addr
+   * @returns {undefined}
+   * @alias multiaddr.add
+   * @memberof PeerInfo#
+   */
   this.multiaddr.add = (addr) => {
     addr = ensureMultiaddr(addr)
 
@@ -46,7 +79,21 @@ function PeerInfo (peerId) {
     }
   }
 
-  // to prevent multiaddr explosion
+  /**
+   * The `addSafe` call, in comparison to `add`, will only add the multiaddr to
+   * `multiaddrs` if the same multiaddr tries to be added twice.
+   *
+   * This is a simple mechanism to prevent `multiaddrs` from becoming bloated with
+   * unusable addresses, which happens when we exchange observed multiaddrs with
+   * peers which will not provide a useful multiaddr to be shared to the rest of the
+   * network (e.g. a multiaddr referring to a peer inside a LAN being shared to the
+   * outside world).
+   *
+   * @param {Multiaddr} addr
+   * @returns {undefined}
+   * @alias multiaddr.addSafe
+   * @memberof PeerInfo#
+   */
   this.multiaddr.addSafe = (addr) => {
     addr = ensureMultiaddr(addr)
 
@@ -63,6 +110,14 @@ function PeerInfo (peerId) {
     }
   }
 
+  /**
+   * Removes a multiaddress instance `addr` from `peer`.
+   *
+   * @param {Multiaddr} addr
+   * @returns {undefined}
+   * @alias multiaddr.rm
+   * @memberof PeerInfo#
+   */
   this.multiaddr.rm = (addr) => {
     addr = ensureMultiaddr(addr)
 
@@ -74,6 +129,16 @@ function PeerInfo (peerId) {
     })
   }
 
+  /**
+   * Removes the array of multiaddresses `existing` from `peer`, and adds the array
+   * of multiaddresses `fresh`.
+   *
+   * @param {Array} existing
+   * @param {Array} fresh
+   * @returns {undefined}
+   * @alias multiaddr.replace
+   * @memberof PeerInfo#
+   */
   this.multiaddr.replace = (existing, fresh) => {
     if (!Array.isArray(existing)) {
       existing = [existing]
@@ -89,17 +154,19 @@ function PeerInfo (peerId) {
     })
   }
 
-  this.distinctMultiaddr = () => {
-    var result = uniqBy(this.multiaddrs, function (item) {
-      return [item.toOptions().port, item.toOptions().transport].join()
-    })
-    return result
-  }
-
   // TODO: add features to fetch multiaddr using filters
   // look at https://github.com/whyrusleeping/js-mafmt/blob/master/src/index.js
 }
 
+/**
+ * Creates a new PeerInfo instance and if no `id` is passed it
+ * generates a new underlying [PeerID](https://github.com/libp2p/js-peer-id)
+ * for it.
+ *
+ * @param {PeerId=} id
+ * @param {function(Error, PeerInfo)} callback
+ * @returns {undefined}
+ */
 PeerInfo.create = (id, callback) => {
   if (typeof id === 'function') {
     callback = id