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..c6e601b 100644
--- a/.npmignore
+++ b/.npmignore
@@ -26,3 +26,4 @@ build/Release
 .node_repl_history
 
 test
+docs
\ No newline at end of file
diff --git a/README.md b/README.md
index 46f9ac0..7abd032 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,4 @@
-Peer Book JavaScript Implementation
-===================================
+# Peer Book JavaScript Implementation
 
 [![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](http://ipn.io)
 [![](https://img.shields.io/badge/freenode-%23ipfs-blue.svg?style=flat-square)](http://webchat.freenode.net/?channels=%23ipfs)
@@ -38,16 +37,8 @@ Loading this module through a script tag will make the `PeerBook` obj available
 <script src="https://unpkg.com/peer-book/dist/index.js"></script>
 ```
 
-# Usage
+## Usage
 
-### `put`
-
-### `get`
-
-### `getByB58String`
-
-### `getByMultihash`
-
-# License
+## License
 
 MIT
diff --git a/package.json b/package.json
index b8fdb13..3424b80 100644
--- a/package.json
+++ b/package.json
@@ -12,15 +12,16 @@
     "test": "aegir-test",
     "test:node": "aegir-test node",
     "test:browser": "aegir-test browser",
-    "release": "aegir-release",
-    "release-minor": "aegir-release --type minor",
-    "release-major": "aegir-release --type major",
+    "docs": "aegir-docs",
+    "release": "aegir-release --docs",
+    "release-minor": "aegir-release --type minor --docs",
+    "release-major": "aegir-release --type major --docs",
     "coverage": "aegir-coverage",
     "coverage-publish": "aegir-coverage publish"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/diasdavid/js-peer-book.git"
+    "url": "git+https://github.com/libp2p/js-peer-book.git"
   },
   "pre-commit": [
     "lint",
@@ -33,18 +34,18 @@
   "author": "David Dias <daviddias@ipfs.io>",
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/diasdavid/js-peer-book/issues"
+    "url": "https://github.com/libp2p/js-peer-book/issues"
   },
-  "homepage": "https://github.com/diasdavid/js-peer-book#readme",
+  "homepage": "https://github.com/libp2p/js-peer-book#readme",
   "dependencies": {
-    "bs58": "^3.0.0"
+    "bs58": "^3.1.0"
   },
   "devDependencies": {
-    "aegir": "^9.1.1",
-    "async": "^2.1.2",
+    "aegir": "^9.2.0",
+    "async": "^2.1.4",
     "chai": "^3.5.0",
-    "multiaddr": "^2.0.3",
-    "peer-info": "^0.8.0",
+    "multiaddr": "^2.1.1",
+    "peer-info": "^0.8.1",
     "pre-commit": "^1.1.3"
   },
   "contributors": [
diff --git a/src/index.js b/src/index.js
index 8e0902a..66c2982 100644
--- a/src/index.js
+++ b/src/index.js
@@ -4,6 +4,11 @@ const bs58 = require('bs58')
 
 module.exports = PeerBook
 
+/**
+ * Peer storage for libp2p and IPFS.
+ *
+ * @class PeerBook
+ */
 function PeerBook () {
   if (!(this instanceof PeerBook)) {
     return new PeerBook()
@@ -11,6 +16,13 @@ function PeerBook () {
 
   const peers = {}
 
+  /**
+   * Add a new peer.
+   *
+   * @param {PeerInfo} peerInfo
+   * @param {boolean} [replace=false] - Should this replace an existing entry.
+   * @returns {undefined}
+   */
   this.put = (peerInfo, replace) => {
     if (peers[peerInfo.id.toB58String()] && !replace) {
       // peerInfo.replace merges by default
@@ -19,10 +31,21 @@ function PeerBook () {
     peers[peerInfo.id.toB58String()] = peerInfo
   }
 
+  /**
+   * List all currently available peers.
+   *
+   * @returns {Object} A map of `base58` encoded peer ids to the full `PeerInfo`.
+   */
   this.getAll = () => {
     return peers
   }
 
+  /**
+   * Get a peer by `base58` encoded id.
+   *
+   * @param {string} b58String - A `base58` encoded peer id.
+   * @returns {PeerInfo}
+   */
   this.getByB58String = (b58String) => {
     const peerInfo = peers[b58String]
     if (peerInfo) {
@@ -31,17 +54,35 @@ function PeerBook () {
     throw new Error('PeerInfo not found')
   }
 
+  /**
+   * Get a peer by multihash.
+   *
+   * @param {Buffer} multihash - A peer id as multihash.
+   * @returns {PeerInfo}
+   */
   this.getByMultihash = (multihash) => {
     const b58multihash = bs58.encode(multihash).toString()
     return this.getByB58String(b58multihash)
   }
 
+  /**
+   * Remove a peer by `base58` encoded id.
+   *
+   * @param {string} b58String - A `base58` encoded peer id.
+   * @returns {undefined}
+   */
   this.removeByB58String = (b58String) => {
     if (peers[b58String]) {
       delete peers[b58String]
     }
   }
 
+  /**
+   * Remove a peer by multihash.
+   *
+   * @param {Buffer} multihash - A peer id as multihash.
+   * @returns {undefined}
+   */
   this.removeByMultihash = (multihash) => {
     const b58multihash = bs58.encode(multihash).toString()
     this.removeByB58String(b58multihash)