From 1a757d83d8b8e12f46fe15cf5c2849195f5bc01d Mon Sep 17 00:00:00 2001
From: Stephen Whitmore <stephen.whitmore@gmail.com>
Date: Mon, 11 Apr 2016 16:35:15 -0700
Subject: [PATCH 1/2] readme <3

---
 README.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 85 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 7f20113..dd40eb2 100644
--- a/README.md
+++ b/README.md
@@ -7,16 +7,95 @@ peer-info JavaScript implementation
 [![Dependency Status](https://david-dm.org/diasdavid/js-peer-info.svg?style=flat-square)](https://david-dm.org/diasdavid/js-peer-info)
 [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/feross/standard)
 
-> Peer Info contains information about a peer Id and its multiaddrs. This module is used by IPFS and libp2p.
+> A PeerInfo object contains information about a
+> [PeerID](https://github.com/diasdavid/js-peer-id) and its
+> [multiaddrs](https://github.com/jbenet/js-multiaddr). This module is used by
+> [IPFS](https://github.com/ipfs/ipfs) and
+> [libp2p](https://github.com/diasdavid/js-libp2p).
 
-# Usage
+# Example
 
-### In Node.js through npm
+```js
+const PeerInfo = require('peer-info')
+const multiaddr = require('multiaddr')
+
+const peer = new PeerInfo()
+
+// TCP port 5001
+peer.multiaddr.add(multiaddr('/ip4/1.2.3.4/tcp/5001'))
 
-```bash
-> npm install --save peer-info
+// UDP port 8001
+peer.multiaddr.add(multiaddr('/ip4/1.2.3.4/udp/8001'))
+
+// mic/speaker soundwaves using frequencies 697 and 1209
+peer.multiaddr.add(multiaddr('/sonic/bfsk/697/1209'))
 ```
 
-```javascript
+# API
+
+```js
 const PeerInfo = require('peer-info')
 ```
+
+## const peer = new PeerInfo()
+
+Creates a new PeerInfo instance and also generates a new underlying
+[PeerID](https://github.com/diasdavid/js-peer-id) for it.
+
+## const peer = new PeerInfo(peerId)
+
+Creates a new PeerInfo instance from an existing PeerID.
+
+## peer.multiaddrs
+
+A list of multiaddresses instances that `peer` can be reached at.
+
+## peer.multiaddr.add(addr)
+
+Adds a new multiaddress that `peer` can be reached at. `addr` is an instance of
+a [multiaddr](https://github.com/jbenet/js-multiaddr).
+
+## peer.multiaddr.addSafe(addr)
+
+Adds a new multiaddress that `peer` can be reached at.
+
+..Safely? **TODO**
+
+## peer.multiaddr.rm(addr)
+
+Removes a multiaddress instance `addr` from `peer`.
+
+## peer.multiaddr.replace(existing, fresh)
+
+Removes the array of multiaddresses `existing` from `peer`, and adds the array
+of multiaddresses `fresh`.
+
+
+# Installation
+
+## npm
+
+```sh
+> npm i peer-info
+```
+
+## Node.JS, Browserify, Webpack
+
+```JavaScript
+var PeerInfo = require('peer-info')
+```
+
+## Browser: `<script>` Tag
+
+Loading this module through a script tag will make the `PeerInfo` obj available
+in the global namespace.
+
+```html
+<script src="https://npmcdn.com/peer-info/dist/index.min.js"></script>
+<!-- OR -->
+<script src="https://npmcdn.com/peer-info/dist/index.js"></script>
+```
+
+# License
+
+MIT

From c8f577ad84674cea3659e53fc931085a0295b077 Mon Sep 17 00:00:00 2001
From: Stephen Whitmore <stephen.whitmore@gmail.com>
Date: Tue, 12 Apr 2016 10:41:14 -0700
Subject: [PATCH 2/2] addSafe notes

---
 README.md | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index dd40eb2..37596d2 100644
--- a/README.md
+++ b/README.md
@@ -57,9 +57,14 @@ a [multiaddr](https://github.com/jbenet/js-multiaddr).
 
 ## peer.multiaddr.addSafe(addr)
 
-Adds a new multiaddress that `peer` can be reached at.
-
-..Safely? **TODO**
+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).
 
 ## peer.multiaddr.rm(addr)