From a3efadd2c2d5d77911ec10efdffc05b573e4c1d5 Mon Sep 17 00:00:00 2001
From: Stephen Whitmore <stephen.whitmore@gmail.com>
Date: Mon, 11 Apr 2016 16:01:48 -0700
Subject: [PATCH] readme <3

---
 README.md | 218 +++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 165 insertions(+), 53 deletions(-)

diff --git a/README.md b/README.md
index a0dd3616..4a9ba51a 100644
--- a/README.md
+++ b/README.md
@@ -10,108 +10,220 @@ js-multiaddr
 
 > [multiaddr](https://github.com/jbenet/multiaddr) implementation in JavaScript.
 
-# Usage
+# What is multiaddr?
 
-### In Node.js through npm
+A standard way to represent addresses that
 
-```bash
-> npm install multiaddr --save
+- support any standard network protocol
+- are self-describing
+- have a binary packed format
+- have a nice string representation
+- encapsulate well
+
+# Example
+
+```js
+$ node
+
+> const multiaddr = require('multiaddr')
+
+> const addr = multiaddr("/ip4/127.0.0.1/udp/1234")
+<Multiaddr /ip4/127.0.0.1/udp/1234>
+
+> addr.buffer
+<Buffer 04 7f 00 00 01 11 04 d2>
+
+> addr.toString()
+'/ip4/127.0.0.1/udp/1234'
+
+> addr.protos()
+[
+  {code: 4, name: 'ip4', size: 32},
+  {code: 17, name: 'udp', size: 16}
+]
+
+> addr.nodeAddress()
+{
+  family: "IPv4",
+  port: 1234,
+  address: "127.0.0.1"
+}
+
+> addr.encapsulate('/sctp/5678')
+<Multiaddr /ip4/127.0.0.1/udp/1234/sctp/5678>
 ```
 
-```JavaScript
+# API
+
+```js
 const multiaddr = require('multiaddr')
 ```
 
-### In the Browser through Webpack
+## Create
 
-Same as in Node.js, you just have to transpile it with Webpack before serving the code. Follow the webpack config example.
+### const addr = multiaddr(str)
 
-### In the Browser through browserify
+Creates a multiaddress from a string (e.g. `/ip4/127.0.0.1/udp/1234`).
 
-Same as in Node.js, you just have to [browserify](https://github.com/substack/node-browserify) the code before serving it. See the browserify repo for how to do that.
+### const addr = multiaddr(buf)
 
-### In the Browser through `<script>` tag
+Creates a multiaddress from another multiaddress' raw bytes.
 
-Make the [multiaddr.js](/dist/multiaddr.js) available through your server and load it using a normal `<script>` tag, this will export the `multiaddr` on the `window` object, such that:
+### addr.buffer
 
-```JavaScript
-const multiaddr = window.multiaddr
-```
+The raw bytes representing this multiaddress.
 
-#### Gotchas
+### addr.toString()
 
-You will need to use Node.js `Buffer` API compatible, if you are running inside the browser, you can access it by `multiaddr.Buffer` or you can install Feross's [Buffer](https://github.com/feross/buffer).
+The multiaddress in string format (e.g. `/ip4/127.0.0.1/udp/1234`).
 
-# Examples
 
-### Simple
+## Protocols
 
-```JavaScript
-const multiaddr = require('multiaddr')
-const addr = multiaddr("/ip4/127.0.0.1/udp/1234")
-// <Multiaddr /ip4/127.0.0.1/udp/1234>
-addr.buffer
-// <Buffer >
-addr.toString()
-// /ip4/127.0.0.1/udp/1234
+### addr.protoCodes()
 
-// construct with Buffer
-addr = multiaddr(addr.buffer)
-// <Multiaddr /ip4/127.0.0.1/udp/1234>
-```
-
-### Protocols
+Returns the codes of the protocols in the multiaddress, in left-to-right order.
 
-```JavaScript
-// get the multiaddr protocol codes
+```js
 addr.protoCodes()
 // [4, 6]
+```
 
-// get the multiaddr protocol string codes
+### addr.protoNames()
+
+Returns the names of the protocols in the multiaddress, in left-to-right order.
+
+```js
 addr.protoNames()
 // ['ip4', 'tcp']
+```
+
+### addr.protos()
 
-// get the multiaddr protocol description objects
+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}]
+// [
+//   { code: 4, name: 'ip4', size: 32},
+//   { code: 17, name: 'udp', size: 16}
+// ]
 ```
 
-### Other formats
+Each object contains the protocol code, protocol name, and the size of its
+address space in bits.
 
-```JavaScript
-// get a node friendly address object
+## 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 no UDP :(
+// { 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')
-// /ip4/127.0.0.1/udp/1234
+// <Multiaddr /ip4/127.0.0.1/udp/1234>
+```
 
-// handles the stupid string version too
+### 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>
-addr.toStupidString(buf)
-// udp4://127.0.0.1:1234
 ```
 
-### En/decapsulate
+*NOT IMPLEMENTED*
 
-```JavaScript
+### 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('/udp') // up to + inc last occurrence of this subaddr
+```
+
+### 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
+## Tunneling
 
-Multiaddr allows expressing tunnels very nicely.
+Given these encapsulation/decapsulate tools, multiaddresses lend
+themselves to expressing tunnels very nicely:
 
 ```JavaScript
 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>
+```
+
+# Installation
 
-const proxyAgain = printerOverProxy.decapsulate('/ip4')
-// <Multiaddr /ip4/10.20.30.40/tcp/443>
+### Node.js + npm
+
+```bash
+$ npm install multiaddr --save
 ```
+### Browser + Webpack
+
+Same as in Node.js, you just have to transpile it with Webpack before serving
+the code. Follow the [webpack config
+example](/webpack.config.js).
+
+### Browser + Browserify
+
+Same as in Node.js, you just have to
+[browserify](https://github.com/substack/node-browserify) the code before
+serving it.
+
+### Browser + `<script>` Tag
+
+Make the [multiaddr.js](/dist/multiaddr.js) available through your server and
+load it using a normal `<script>` tag. This will export the `multiaddr` on the
+`window` object:
+
+```JavaScript
+const multiaddr = window.multiaddr
+```
+
+**NOTE**: You will need access to the Node.js `Buffer` API. If you are running
+in the browser, you can access it with `multiaddr.Buffer` or you can install
+[feross/buffer](https://github.com/feross/buffer).
+
+# License
+
+MIT