move method comments to api doc

1 files changed, 24 insertions, 13 deletions

diff --git a/docs/api.md b/docs/api.md
index b6f5201..b0e3eba 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -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,17 @@ 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.
 
@@ -261,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)
@@ -269,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)`