Merge pull request #762 from feross/fixes-for-desktop

BREAKING: Many fixes; all leaks fixed

1 files changed, 32 insertions, 18 deletions

diff --git a/docs/api.md b/docs/api.md
index 124899d..b0e3eba 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:
 
@@ -201,6 +201,10 @@ Magnet URI of the torrent (string).
 Array of all files in the torrent. See documentation for `File` below to learn what
 methods/properties files have.
 
+## `torrent.timeRemaining`
+
+Time remaining for download to complete (in milliseconds).
+
 ## `torrent.received`
 
 Total bytes received from peers (*including* invalid data).
@@ -213,10 +217,6 @@ Total *verified* bytes received from peers.
 
 Total bytes uploaded to peers.
 
-## `torrent.timeRemaining`
-
-Time remaining for download to complete (in milliseconds).
-
 ## `torrent.downloadSpeed`
 
 Torrent download speed, in bytes/sec.
@@ -241,15 +241,19 @@ Number of peers in the torrent swarm.
 
 Torrent download location.
 
-## `torrent.destroy()`
+## `torrent.destroy([callback])`
 
-Alias for `client.remove(torrent)`.
+Alias for `client.remove(torrent)`. If `callback` is provided, it will be called when
+the torrent is fully destroyed, i.e. all open sockets are closed, and the storage is
+closed.
 
 ## `torrent.addPeer(peer)`
 
-Adds a peer to the torrent swarm. Normally, you don't need to call `torrent.addPeer()`.
-WebTorrent will automatically find peers using the tracker servers or DHT. This is just
-for manually adding a peer to the client.
+Add a peer to the torrent swarm. This is advanced functionality. Normally, you should not
+need to call `torrent.addPeer()` manually. 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.
 
@@ -259,7 +263,7 @@ instance (for WebRTC peers).
 
 ## `torrent.addWebSeed(url)`
 
-Adds a web seed to the torrent swarm. For more information on BitTorrent web seeds, see
+Add a web seed to the torrent swarm. For more information on BitTorrent web seeds, see
 [BEP19](http://www.bittorrent.org/beps/bep_0019.html).
 
 In the browser, web seed servers must have proper CORS (Cross-origin resource sharing)
@@ -267,11 +271,20 @@ headers so that data can be fetched across domain.
 
 The `url` argument is the web seed URL.
 
+## `torrent.removePeer(peer)`
+
+Remove a peer from the torrent swarm. This is advanced functionality. Normally, you should
+not need to call `torrent.removePeer()` manually. WebTorrent will automatically remove
+peers from the torrent swarm when they're slow or don't have pieces that are needed.
+
+The `peer` argument should be an address (i.e. "ip:port" string), a peer id (hex string),
+or `simple-peer` instance.
+
 ## `torrent.select(start, end, [priority], [notify])`
 
-Selects a range of pieces to prioritize starting with `start` and ending with `end` (both inclusive)
-at the given `priority`. `notify` is an optional callback to be called when the selection is updated
-with new data.
+Selects a range of pieces to prioritize starting with `start` and ending with `end` (both
+inclusive) at the given `priority`. `notify` is an optional callback to be called when the
+selection is updated with new data.
 
 ## `torrent.deselect(start, end, priority)`
 
@@ -452,7 +465,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 +476,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