docs(api): first pass

.gitignore

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

.npmignore

@@ -26,4 +26,4 @@ build/Release
 # https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git
 node_modules
 
-test
+test

README.md

@@ -118,146 +118,7 @@ $ node
 
 ## API
 
-```js
-const multiaddr = require('multiaddr')
-```
-
-### Create
-
-#### const addr = multiaddr(str)
-
-Creates a multiaddress from a string (e.g. `/ip4/127.0.0.1/udp/1234`).
-
-#### const addr = multiaddr(buf)
-
-Creates a multiaddress from another multiaddress' raw bytes.
-
-#### addr.buffer
-
-The raw bytes representing this multiaddress.
-
-#### addr.toString()
-
-The multiaddress in string format (e.g. `/ip4/127.0.0.1/udp/1234`).
-
-### Protocols
-
-#### addr.protoCodes()
-
-Returns the codes of the protocols in the multiaddress, in left-to-right order.
-
-```js
-addr.protoCodes()
-// [4, 6]
-```
-
-#### addr.protoNames()
-
-Returns the names of the protocols in the multiaddress, in left-to-right order.
-
-```js
-addr.protoNames()
-// ['ip4', 'tcp']
-```
-
-#### addr.protos()
-
-Returns description objects of the protocols in the multiaddress, in left-to-right order.
-
-```js
-addr.protos()
-// [
-//   { code: 4, name: 'ip4', size: 32},
-//   { code: 17, name: 'udp', size: 16}
-// ]
-```
-
-Each object contains the protocol code, protocol name, and the size of its
-address space in bits.
-
-### Node-Friendly Addresses
-
-Utility functions for getting NodeJS-friendly address information from a
-multiaddress.
-
-#### addr.nodeAddress()
-
-Returns a NodeJS-friendly object describing the left-most address in the
-multiaddress.
-
-```js
-addr.nodeAddress()
-// { family: "IPv4", port:1234, address: "127.0.0.1" }
-```
-
-Note that protocol information is left out: in Node (and most network systems)
-the protocol is unknowable given only the address.
-
-#### addr.fromNodeAddress(addr)
-
-Constructs a multiaddress, given a NodeJS-friendly address object and a protocol.
-
-```js
-addr.fromNodeAddress({family: "IPv4", port:1234, address: "127.0.0.1"}, 'udp')
-// <Multiaddr /ip4/127.0.0.1/udp/1234>
-```
-
-#### addr.fromStupidString(str)
-
-Returns a multiaddress, given a URI in the format `<proto><IPv>://<IP
-Addr>[:<proto port>]`
-
-```js
-addr = multiaddr.fromStupidString("udp4://127.0.0.1:1234")
-// <Multiaddr /ip4/127.0.0.1/udp/1234>
-```
-
-*NOT IMPLEMENTED*
-
-#### addr.toStupidString()
-
-*NOT IMPLEMENTED*
-
-### En/decapsulate
-
-#### addr.encapsulate(str)
-
-Returns a new multiaddress that encapsulates `addr` in a new protocol string,
-`str`.
-
-```js
-addr.encapsulate('/sctp/5678')
-// <Multiaddr /ip4/127.0.0.1/udp/1234/sctp/5678>
-```
-
-#### addr.decapsulate(str)
-
-Returns a new multiaddress with the right-most protocol string `str` removed.
-
-```js
-multiaddress('/ip4/127.0.0.1/udp/1234').decapsulate('/udp')
-// <Multiaddr /ip4/127.0.0.1>
-```
-
-### Tunneling
-
-Given these encapsulation/decapsulate tools, multiaddresses lend
-themselves to expressing tunnels very nicely:
-
-```js
-const printer = multiaddr('/ip4/192.168.0.13/tcp/80')
-
-const proxy = multiaddr('/ip4/10.20.30.40/tcp/443')
-
-const printerOverProxy = proxy.encapsulate(printer)
-// <Multiaddr /ip4/10.20.30.40/tcp/443/ip4/192.168.0.13/tcp/80>
-```
-
-### Misc
-
-#### `multiaddr.isMultiaddr(addr)`
-
-Returns `true` if the passed in `addr` is a valid `multiaddr`.
+TODO: Moved to API-docs, insert link here
 
 ## Maintainers
 

documentation.yml

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

intro.md

@@ -0,0 +1,84 @@
+JavaScript implementation of [Multiaddr](https://github.com/multiformats/multiaddr).
+
+## What is multiaddr?
+
+Multiaddr is a standard way to represent addresses that: 
+- Support any standard network protocols.
+- Self-describe (include protocols).
+- Have a binary packed format.
+- Have a nice string representation.
+- Encapsulate well.
+
+You can read more about what Multiaddr is in the language-independent Github repository: 
+https://github.com/multiformats/multiaddr
+
+Multiaddr is a part of a group of values called [Multiformats](https://github.com/multiformats/multiformats)
+
+## Example
+
+```js
+var Multiaddr = require('multiaddr')
+
+var home = new Multiaddr('/ip4/127.0.0.1/tcp/80')
+// <Multiaddr 047f000001060050 - /ip4/127.0.0.1/tcp/80>
+
+home.buffer
+// <Buffer 04 7f 00 00 01 06 00 50>
+
+home.toString()
+// '/ip4/127.0.0.1/tcp/80'
+
+home.protos()
+// [ { code: 4, size: 32, name: 'ip4' },
+//   { code: 6, size: 16, name: 'tcp' } ]
+
+home.nodeAddress()
+// { family: 'IPv4', address: '127.0.0.1', port: '80' }
+
+var proxy = new Multiaddr('/ip4/192.168.2.1/tcp/3128')
+// <Multiaddr 04c0a80201060c38 - /ip4/192.168.2.1/tcp/3128>
+
+var full = proxy.encapsulate(home)
+// <Multiaddr 04c0a80201060c38047f000001060050 - /ip4/192.168.2.1/tcp/3128/ip4/127.0.0.1/tcp/80>
+
+full.toString()
+// '/ip4/192.168.2.1/tcp/3128/ip4/127.0.0.1/tcp/80'
+```
+
+## Installation
+
+### npm
+
+```sh
+> npm install multiaddr
+```
+
+## Setup
+
+### Node.js
+
+```js
+var Multiaddr = require('multiaddr')
+```
+
+### Browser: Browserify, Webpack, other bundlers
+
+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 asset management
+process.
+
+```js
+var Multiaddr = require('multiaddr')
+```
+
+### Browser: `<script>` Tag
+
+Loading this module through a script tag will make the `Multiaddr` obj available in
+the global namespace.
+
+```html
+<script src="https://unpkg.com/multiaddr/dist/index.min.js"></script>
+<!-- OR -->
+<script src="https://unpkg.com/multiaddr/dist/index.js"></script>
+```

package.json

@@ -13,7 +13,8 @@
     "release-minor": "aegir-release --type minor",
     "release-major": "aegir-release --type major",
     "coverage": "aegir-coverage",
-    "coverage-publish": "aegir-coverage publish"
+    "coverage-publish": "aegir-coverage publish",
+    "docs": "aegir-docs"
   },
   "pre-commit": [
     "lint",
@@ -44,7 +45,7 @@
     "xtend": "^4.0.1"
   },
   "devDependencies": {
-    "aegir": "^9.1.2",
+    "aegir": "^9.3.0",
     "buffer-loader": "0.0.1",
     "chai": "^3.5.0",
     "pre-commit": "^1.1.3"
@@ -58,4 +59,4 @@
     "Stephen Whitmore <stephen.whitmore@gmail.com>",
     "npm-to-cdn-bot (by Forbes Lindesay) <npmcdn-to-unpkg-bot@users.noreply.github.com>"
   ]
-}
+}