BREAKING: Major cleanup

### Added

- `client.listening` property to signal whether TCP server is listening
for incoming
  connections.

### Changed

- Merged `Swarm` class into `Torrent` object. Properties on
`torrent.swarm` (like
  `torrent.swarm.wires`) now exist on `torrent` (e.g. `torrent.wires`).

- `torrent.addPeer` can no longer be called before the `infoHash` event
has been
  emitted.

- Remove `torrent.on('listening')` event. Use `client.on('listening')`
instead.

- Remove support from `TCPPool` for listening on multiple ports. This
was not used by
  WebTorrent and just added complexity. There is now a single `TCPPool`
instance for the
  whole WebTorrent client.

- Deprecate: Do not use `client.download()` anymore. Use `client.add()`
instead.

- Deprecate: Do not use `torrent.swarm` anymore. Use `torrent` instead.

### Fixed

- When there is a `torrent.on('error')` listener, don't also emit
  `client.on('error')`.

- Do not return existing torrent object when duplicate torrent is
added. Fire an
  `'error'` event instead.

- Memory leak of `Torrent` object caused by `RarityMap`

- Memory leak of `Torrent` object caused by `TCPPool`

- `client.ratio` and `torrent.ratio` are now calculated as `uploaded /
received` instead
  of `uploaded / downloaded`.

1 files changed, 8 insertions, 5 deletions

diff --git a/docs/api.md b/docs/api.md
index 124899d..b6f5201 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -63,7 +63,7 @@ If `opts` is specified, then the default options (shown below) will be overridde
 
 ## `client.add(torrentId, [opts], [function ontorrent (torrent) {}])`
 
-Start downloading a new torrent. Aliased as `client.download`.
+Start downloading a new torrent.
 
 `torrentId` can be one of:
 
@@ -251,6 +251,8 @@ Adds a peer to the torrent swarm. Normally, you don't need to call `torrent.addP
 WebTorrent will automatically find peers using the tracker servers or DHT. This is just
 for manually adding a peer to the client.
 
+This method should not be called until the `infoHash` event has been emitted.
+
 Returns `true` if peer was added, `false` if peer was blocked by the loaded blocklist.
 
 The `peer` argument must be an address string in the format `12.34.56.78:4444` (for
@@ -452,7 +454,7 @@ called once the file is ready. `callback` must be specified, and will be called
 ```js
 file.getBuffer(function (err, buffer) {
   if (err) throw err
-  console.log(buffer) // <Buffer 00 98 00 01 01 00 00 00 50 ae 07 04 01 00 00 00 0a 00 00 00 00 00 00 00 78 ae 07 04 01 00 00 00 05 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ...>
+  console.log(buffer) // <Buffer 00 98 00 01 ...>
 })
 ```
 
@@ -463,9 +465,10 @@ that handles many file types like video (.mp4, .webm, .m4v, etc.), audio (.m4a,
 .wav, etc.), images (.jpg, .gif, .png, etc.), and other file formats (.pdf, .md, .txt,
 etc.).
 
-The file will be fetched from the network with highest priority and streamed into the
-page (if it's video or audio). In some cases, video or audio files will not be streamable
-because they're not in a format that the browser can stream so the file will be fully downloaded before being played. For other non-streamable file types like images and PDFs,
+The file will be fetched from the network with highest priority and streamed into the page
+(if it's video or audio). In some cases, video or audio files will not be streamable
+because they're not in a format that the browser can stream so the file will be fully
+downloaded before being played. For other non-streamable file types like images and PDFs,
 the file will be downloaded then displayed.
 
 `rootElem` is a container element (CSS selector or reference to DOM node) that the content