Adds JSDocs and updates example code.

example/portscan.js

@@ -1,16 +1,38 @@
-var portscanner = require('../lib/portscanner.js')
+var http        = require('http')
+  , portscanner = require('../lib/portscanner.js')
 
-portscanner.checkPortStatus(3000, 'localhost', function(error, status) {
-  console.log(status)
-})
+// Sets up an HTTP server listening on port 3005
+var server = http.createServer(function (request, response) {
 
-portscanner.findAnOpenPort(3000, 3010, 'localhost', function(error, port) {
-  console.log('OPEN PORT AT ' + port)
 })
+server.listen(3005, 'localhost')
 
-portscanner.findAClosedPort(3000, 3010, 'localhost', function(error, port) {
-  console.log('CLOSED PORT AT ' + port)
-})
+// Waits briefly before port scanning to let the HTTP server start listening
+setTimeout(function() {
+
+  // Checks the status of an individual port.
+  portscanner.checkPortStatus(3005, 'localhost', function(error, status) {
+    // Status should be 'open' since the HTTP server is listening on that port
+    console.log('Status at port 3005 is ' + status)
+  })
+
+  portscanner.checkPortStatus(3000, 'localhost', function(error, status) {
+    // Status should be 'closed' since no service is listening on that port.
+    console.log('Status at port 3000 is ' + status)
+  })
+
+  // Finds a port that a service is listening on
+  portscanner.findAnOpenPort(3000, 3010, 'localhost', function(error, port) {
+    // Port should be 3005 as the HTTP server is listening on that port
+    console.log('Found an open port at ' + port)
+  })
+
+  // Finds a port that is not currently in use
+  portscanner.findAClosedPort(3000, 3010, 'localhost', function(error, port) {
+    // Will return any number between 3000 and 3010 (inclusive), that's not 3005.
+    // The order is unknown as the port status checks are asynchronous.
+    console.log('Found a closed port at ' + port)
+  })
 
-setTimeout(function() { }, 10000)
+}, 500)
 

lib/portscanner.js

@@ -3,44 +3,75 @@ var net    = require('net')
 
 var portscanner = exports
 
-
+/**
+ * Finds the first port with a status of 'open', implying the port is in use and
+ * a service listening on it.
+ *
+ * @param {Number} startPort - port to begin status check
+ * @param {Number} endPort - last port to check status on (defaults to 65535)
+ * @param {String} host - where to scan
+ * @param {Function} callback - function (error, port) { ... }
+ *   - {Object|null} error - any errors that occurred while port scanning
+ *   - {Number|Boolean} port - The first open port found. Note, this is the
+ *     first port that returns status as 'open', not necessarily the first open
+ *     port checked. If no open port is found, value is false.
+ */
 portscanner.findAnOpenPort = function(startPort, endPort, host, callback) {
   findAPortWithStatus('open', startPort, endPort, host, callback)
 }
 
+/**
+ * Finds the first port with a status of 'closed', implying the port is not in
+ * use.
+ *
+ * @param {Number} startPort - port to begin status check
+ * @param {Number} endPort - last port to check status on (defaults to 65535)
+ * @param {String} host - where to scan
+ * @param {Function} callback - function (error, port) { ... }
+ *   - {Object|null} error - any errors that occurred while port scanning
+ *   - {Number|Boolean} port - The first closed port found. Note, this is the
+ *     first port that returns status as 'closed', not necessarily the first
+ *     closed port checked. If no closed port is found, value is false.
+ */
 portscanner.findAClosedPort = function(startPort, endPort, host, callback) {
   findAPortWithStatus('closed', startPort, endPort, host, callback)
 
 }
 
+/**
+ * Checks the status of an individual port.
+ *
+ * @param {Number} port - port to check status on
+ * @param {String} host - where to scan
+ * @param {Function} callback - function (error, port) { ... }
+ *   - {Object|null} error - any errors that occurred while port scanning
+ *   - {String} status - 'open' if the port is in use
+ *       'closed' if the port is available
+ */
 portscanner.checkPortStatus = function(port, host, callback) {
+  host = host || 'localhost'
   var socket = new Socket()
 
   // Socket connection established, port is open
   socket.on('connect', function() {
-    console.log('ON CONNECT')
     socket.end()
     callback(null, 'open')
   })
 
   // If no response, assume port is not listening
   socket.setTimeout(400)
   socket.on('timeout', function() {
-    console.log('ON TIMEOUT')
     socket.end()
     callback(null, 'closed')
   })
 
   // Assuming the port is not open if an error. May need to refine based on
   // exception
   socket.on('error', function(exception) {
-    console.log('ON ERROR')
-    //console.log(exception)
     socket.end()
     callback(null, 'closed')
   })
 
-  host = host || 'localhost'
   socket.connect(port, host)
 }