move method comments to api doc

4 files changed, 28 insertions, 113 deletions

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