move method comments to api doc

5 files changed, 52 insertions, 126 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)`
 
diff --git a/lib/file-stream.js b/lib/file-stream.js
index 55355ea..508f358 100644
--- a/lib/file-stream.js
+++ b/lib/file-stream.js
@@ -88,7 +88,6 @@ FileStream.prototype.destroy = function (onclose) {
 
 FileStream.prototype._destroy = function (err, onclose) {
   if (this.destroyed) return
-  if (onclose) this.once('close', onclose)
   this.destroyed = true
 
   if (!this._torrent.destroyed) {
@@ -97,4 +96,5 @@ FileStream.prototype._destroy = function (err, onclose) {
 
   if (err) this.emit('error', err)
   this.emit('close')
+  if (onclose) onclose()
 }
diff --git a/lib/file.js b/lib/file.js
index fd24e0e..bfa032e 100644
--- a/lib/file.js
+++ b/lib/file.js
@@ -1,3 +1,5 @@
+// TODO: cleanup reference to torrent (i.e. Torrent object)
+
 module.exports = File
 
 var eos = require('end-of-stream')
@@ -12,10 +14,6 @@ var streamToBuffer = require('stream-with-known-length-to-buffer')
 
 inherits(File, EventEmitter)
 
-/**
- * @param {Torrent} torrent torrent that the file belongs to
- * @param {Object} file file object from the parsed torrent
- */
 function File (torrent, file) {
   EventEmitter.call(this)
 
@@ -40,33 +38,16 @@ function File (torrent, file) {
   }
 }
 
-/**
- * Selects the file to be downloaded, but at a lower priority than files with streams.
- * Useful if you know you need the file at a later stage.
- */
 File.prototype.select = function (priority) {
   if (this.length === 0) return
   this._torrent.select(this._startPiece, this._endPiece, priority)
 }
 
-/**
- * Deselects the file, which means it won't be downloaded unless someone creates a stream
- * for it.
- */
 File.prototype.deselect = function () {
   if (this.length === 0) return
   this._torrent.deselect(this._startPiece, this._endPiece, false)
 }
 
-/**
- * Create a readable stream to the file. Pieces needed by the stream will be prioritized
- * highly and fetched from the swarm first.
- *
- * @param {Object=} opts
- * @param {number} opts.start start stream at byte (inclusive)
- * @param {number} opts.end end stream at byte (inclusive)
- * @return {FileStream}
- */
 File.prototype.createReadStream = function (opts) {
   var self = this
   if (this.length === 0) {
@@ -89,35 +70,21 @@ File.prototype.createReadStream = function (opts) {
   return fileStream
 }
 
-/**
- * @param {function} cb
- */
 File.prototype.getBuffer = function (cb) {
   streamToBuffer(this.createReadStream(), this.length, cb)
 }
 
-/**
- * @param {function} cb
- */
 File.prototype.getBlobURL = function (cb) {
   if (typeof window === 'undefined') throw new Error('browser-only method')
   var mime = render.mime[path.extname(this.name).toLowerCase()]
   streamToBlobURL(this.createReadStream(), mime, cb)
 }
 
-/**
- * @param {Element|string} elem
- * @param {function} cb
- */
 File.prototype.appendTo = function (elem, cb) {
   if (typeof window === 'undefined') throw new Error('browser-only method')
   render.append(this, elem, cb)
 }
 
-/**
- * @param {Element|string} elem
- * @param {function} cb
- */
 File.prototype.renderTo = function (elem, cb) {
   if (typeof window === 'undefined') throw new Error('browser-only method')
   render.render(this, elem, cb)
diff --git a/lib/torrent.js b/lib/torrent.js
index 6756633..fc5f495 100644
--- a/lib/torrent.js
+++ b/lib/torrent.js
@@ -1,5 +1,4 @@
 // TODO: cleanup event listeners
-// TODO: Remove all inline docs, and move to docs/api.md
 
 /* global URL, Blob */
 
@@ -60,11 +59,6 @@ var TMP = typeof pathExists.sync === 'function'
 
 inherits(Torrent, EventEmitter)
 
-/**
- * @param {string|Buffer|Object} torrentId
- * @param {WebTorrent} client
- * @param {Object=} opts
- */
 function Torrent (torrentId, client, opts) {
   EventEmitter.call(this)
 
@@ -151,7 +145,7 @@ Object.defineProperty(Torrent.prototype, 'downloaded', {
   }
 })
 
-// The number of missing pieces. Used to implement 'end game' mode.
+// TODO: re-enable this. The number of missing pieces. Used to implement 'end game' mode.
 // Object.defineProperty(Storage.prototype, 'numMissing', {
 //   get: function () {
 //     var self = this
@@ -183,8 +177,6 @@ Object.defineProperty(Torrent.prototype, 'numPeers', {
   get: function () { return this.wires.length }
 })
 
-// TODO: remove this (and file.getBlobURL?)
-// Torrent file as a blob url
 Object.defineProperty(Torrent.prototype, 'torrentFileBlobURL', {
   get: function () {
     if (typeof window === 'undefined') throw new Error('browser-only property')
@@ -447,6 +439,7 @@ Torrent.prototype._onMetadata = function (metadata) {
 }
 
 /*
+ * TODO: remove this
  * Gets the last modified time of every file on disk for this torrent.
  * Only valid in Node, not in the browser.
  */
@@ -519,9 +512,6 @@ Torrent.prototype._onStore = function () {
   self._updateSelections()
 }
 
-/**
- * Destroy and cleanup this torrent.
- */
 Torrent.prototype.destroy = function (cb) {
   var self = this
   self._destroy(null, cb)
@@ -575,12 +565,6 @@ Torrent.prototype._destroy = function (err, cb) {
   }
 }
 
-/**
- * Add a peer to the torrent swarm
- * @param {string|simple-peer} peer    "ip:port" string or simple-peer instance
- * @param {string}             peer.id bittorrent peer id (when `peer` is simple-peer)
- * @return {boolean} true if peer was added, false if peer was blocked
- */
 Torrent.prototype.addPeer = function (peer) {
   var self = this
   if (self.destroyed) throw new Error('torrent is destroyed')
@@ -675,11 +659,6 @@ Torrent.prototype._addPeer = function (peer) {
   return newPeer
 }
 
-/**
- * Add a web seed to the torrent swarm.
- * @param {string} url web seed url
- * @param {Object} parsedTorrent
- */
 Torrent.prototype.addWebSeed = function (url) {
   if (this.destroyed) throw new Error('torrent is destroyed')
 
@@ -707,7 +686,6 @@ Torrent.prototype.addWebSeed = function (url) {
 /**
  * Called whenever a new incoming TCP peer connects to this torrent swarm. Called with a
  * peer that has already sent a handshake.
- * @param {Peer} peer
  */
 Torrent.prototype._addIncomingPeer = function (peer) {
   var self = this
@@ -720,10 +698,6 @@ Torrent.prototype._addIncomingPeer = function (peer) {
   self._peersLength += 1
 }
 
-/**
- * Remove a peer from the torrent swarm.
- * @param  {string} peer "ip:port" string, peerId string, or simple-peer instance
- */
 Torrent.prototype.removePeer = function (peer) {
   var self = this
   var id = (peer && peer.id) || peer
@@ -742,14 +716,6 @@ Torrent.prototype.removePeer = function (peer) {
   self._drain()
 }
 
-/**
- * Select a range of pieces to prioritize.
- *
- * @param {number}    start     start piece index (inclusive)
- * @param {number}    end       end piece index (inclusive)
- * @param {number}    priority  priority associated with this selection
- * @param {function}  notify    callback when selection is updated with new data
- */
 Torrent.prototype.select = function (start, end, priority, notify) {
   var self = this
   if (self.destroyed) throw new Error('torrent is destroyed')
@@ -776,13 +742,6 @@ Torrent.prototype.select = function (start, end, priority, notify) {
   self._updateSelections()
 }
 
-/**
- * Deprioritizes a range of previously selected pieces.
- *
- * @param {number}  start     start piece index (inclusive)
- * @param {number}  end       end piece index (inclusive)
- * @param {number}  priority  priority associated with the selection
- */
 Torrent.prototype.deselect = function (start, end, priority) {
   var self = this
   if (self.destroyed) throw new Error('torrent is destroyed')
@@ -801,12 +760,6 @@ Torrent.prototype.deselect = function (start, end, priority) {
   self._updateSelections()
 }
 
-/**
- * Marks a range of pieces as critical priority to be downloaded ASAP.
- *
- * @param {number}  start  start piece index (inclusive)
- * @param {number}  end    end piece index (inclusive)
- */
 Torrent.prototype.critical = function (start, end) {
   var self = this
   if (self.destroyed) throw new Error('torrent is destroyed')
@@ -1530,19 +1483,12 @@ Torrent.prototype.createServer = function (opts) {
   return server
 }
 
-/**
- * Temporarily stop connecting to new peers. Note that this does not pause the streams
- * of existing connections or their wires.
- */
 Torrent.prototype.pause = function () {
   if (this.destroyed) return
   this._debug('pause')
   this.paused = true
 }
 
-/**
- * Resume connecting to new peers.
- */
 Torrent.prototype.resume = function () {
   if (this.destroyed) return
   this._debug('resume')
@@ -1556,23 +1502,6 @@ Torrent.prototype._debug = function () {
   debug.apply(null, args)
 }
 
-function getBlockPipelineLength (wire, duration) {
-  return 2 + Math.ceil(duration * wire.downloadSpeed() / Piece.BLOCK_LENGTH)
-}
-
-function getPiecePipelineLength (wire, duration, pieceLength) {
-  return 1 + Math.ceil(duration * wire.downloadSpeed() / pieceLength)
-}
-
-/**
- * Returns a random integer in [0,high)
- */
-function randomInt (high) {
-  return Math.random() * high | 0
-}
-
-function noop () {}
-
 /**
  * Pop a peer off the FIFO queue and connect to it. When _drain() gets called,
  * the queue will usually have only one peer in it, except when there are too
@@ -1650,3 +1579,20 @@ Torrent.prototype._validAddr = function (addr) {
   return port > 0 && port < 65535 &&
     !(host === '127.0.0.1' && port === this.client.torrentPort)
 }
+
+function getBlockPipelineLength (wire, duration) {
+  return 2 + Math.ceil(duration * wire.downloadSpeed() / Piece.BLOCK_LENGTH)
+}
+
+function getPiecePipelineLength (wire, duration, pieceLength) {
+  return 1 + Math.ceil(duration * wire.downloadSpeed() / pieceLength)
+}
+
+/**
+ * Returns a random integer in [0,high)
+ */
+function randomInt (high) {
+  return Math.random() * high | 0
+}
+
+function noop () {}
diff --git a/lib/webconn.js b/lib/webconn.js
index 945edd4..e3e3a27 100644
--- a/lib/webconn.js
+++ b/lib/webconn.js
@@ -60,9 +60,9 @@ WebConn.prototype.httpRequest = function (pieceIndex, offset, length, cb) {
   var rangeStart = pieceOffset + offset /* offset within whole torrent */
   var rangeEnd = rangeStart + length - 1
 
-  // Web seed URL format
-  // For single-file torrents, you just make HTTP range requests directly to the web seed URL
-  // For multi-file torrents, you have to add the torrent folder and file name to the URL
+  // Web seed URL format:
+  // For single-file torrents, make HTTP range requests directly to the web seed URL
+  // For multi-file torrents, add the torrent folder and file name to the URL
   var files = self.parsedTorrent.files
   var requests
   if (files.length <= 1) {
@@ -75,7 +75,9 @@ WebConn.prototype.httpRequest = function (pieceIndex, offset, length, cb) {
     var requestedFiles = files.filter(function (file) {
       return file.offset <= rangeEnd && (file.offset + file.length) > rangeStart
     })
-    if (requestedFiles.length < 1) return cb(new Error('Could not find file corresponnding to web seed range request'))
+    if (requestedFiles.length < 1) {
+      return cb(new Error('Could not find file corresponnding to web seed range request'))
+    }
 
     requests = requestedFiles.map(function (requestedFile) {
       var fileEnd = requestedFile.offset + requestedFile.length - 1