updated jsdocs for peer and pool

lib/peer.js

@@ -11,27 +11,31 @@ var $ = bitcore.util.preconditions;
 var util = require('util');
 
 /**
- * A Peer instance represents a remote bitcoin node and allows to communicate
- * with it using the standard messages of the bitcoin p2p protocol.
+ * A constructor to create Peer instances to send and recieve messages
+ * using the standard Bitcoin protocol.
  *
  * @example
  * ```javascript
  *
- * var peer = new Peer('127.0.0.1').setProxy('127.0.0.1', 9050);
+ * var peer = new Peer({host: '127.0.0.1'}).setProxy('127.0.0.1', 9050);
  * peer.on('tx', function(tx) {
  *  console.log('New transaction: ', tx.id);
  * });
  * peer.connect();
  * ```
  *
- * @param {String} host - IP address of the remote host
- * @param {Number} [port] - Port number of the remote host
- * @param {Network} [network] - The context for this communication
+ * @param {Object} [options]
+ * @param {String} [options.host] - IP address of the remote host
+ * @param {Number} [options.port] - Port number of the remote host
+ * @param {Network} [options.network=Networks.defaultNetwork] - The network configuration
+ * @param {Boolean} [options.relay] - An option to disable automatic inventory relaying from the remote peer
+ * @param {Socket} [options.socket] - An existing connected socket
+
  * @returns {Peer} A new instance of Peer.
  * @constructor
  */
 function Peer(options) {
-  /* jshint maxstatements: 25 */
+  /* jshint maxstatements: 26 */
   /* jshint maxcomplexity: 8 */
 
   if (!(this instanceof Peer)) {
@@ -95,6 +99,8 @@ function Peer(options) {
     self._sendPong(message.nonce);
   });
 
+  return this;
+
 }
 util.inherits(Peer, EventEmitter);
 
@@ -124,7 +130,7 @@ Peer.prototype.setProxy = function(host, port) {
 
 /**
  * Init the connection with the remote peer.
- * @returns {Socket} The same peer instance.
+ * @returns {Peer} The same peer instance.
  */
 Peer.prototype.connect = function() {
   this.socket = this._getSocket();
@@ -166,7 +172,7 @@ Peer.prototype._onError = function(e) {
 
 /**
  * Disconnects the remote connection.
- * @returns {Socket} The same peer instance.
+ * @returns {Peer} The same peer instance.
  */
 Peer.prototype.disconnect = function() {
   this.status = Peer.STATUS.DISCONNECTED;

lib/pool.js

@@ -22,15 +22,15 @@ function now() {
  * @example
  * ```javascript
  *
- * var pool = new Pool(Networks.livenet);
+ * var pool = new Pool({network: Networks.livenet});
  * pool.on('peerinv', function(peer, message) {
  *   // do something with the inventory announcement
  * });
  * pool.connect();
  * ```
  *
- * @param {Network|String} network - The network to connect
- * @param {Object} [options] - Options object
+ * @param {Object} [options]
+ * @param {Network} [options.network=Networks.defaultNetwork] - The network configuration
  * @param {Boolean} [options.listenAddr=true] - Prevent new peers being added from addr messages
  * @param {Boolean} [options.dnsSeed=true] - Prevent seeding with DNS discovered known peers
  * @param {Boolean} [options.relay=true] - Prevent inventory announcements until a filter is loaded
@@ -115,7 +115,6 @@ Pool.PeerEvents = ['version', 'inv', 'getdata', 'ping', 'pong', 'addr',
   'filterclear'
 ];
 
-
 /**
  * Will initiatiate connection to peers, if available peers have been added to
  * the pool, it will connect to those, otherwise will use DNS seeds to find
@@ -132,7 +131,6 @@ Pool.prototype.connect = function connect() {
   return this;
 };
 
-
 /**
  * Will disconnect all peers that are connected.
  */
@@ -210,6 +208,12 @@ Pool.prototype._connectPeer = function _connectPeer(addr) {
   return this;
 };
 
+/**
+ * Adds a peer with a connected socket to the _connectedPeers object, and
+ * intializes the associated event handlers.
+ * @param {Socket} - socket - A new connected socket
+ * @param {Object} - addr - The associated addr object for the peer
+ */
 Pool.prototype._addConnectedPeer = function _addConnectedPeer(socket, addr) {
   var self = this;
 
@@ -227,6 +231,10 @@ Pool.prototype._addConnectedPeer = function _addConnectedPeer(socket, addr) {
   return this;
 };
 
+/**
+ * Will add disconnect and ready events for a peer and intialize
+ * handlers for relay peer message events.
+ */
 Pool.prototype._addPeerEventHandlers = function(peer, addr) {
   var self = this;
 
@@ -329,6 +337,10 @@ Pool.prototype.inspect = function inspect() {
     this._addrs.length + '>';
 };
 
+/**
+ * Will send a message to all of the peers in the pool.
+ * @param {Message} message - An instance of the message to send
+ */
 Pool.prototype.sendMessage = function(message) {
   // broadcast to peers
   for(var key in this._connectedPeers) {
@@ -337,6 +349,10 @@ Pool.prototype.sendMessage = function(message) {
   }
 };
 
+/**
+ * Will enable a listener for peer connections, when a peer connects
+ * it will be added to the pool.
+ */
 Pool.prototype.listen = function() {
   var self = this;