Renames port finding functions for clarity.

The original names of `findAnOpenPort` and `findAClosedPort` were ambiguous.
While the functions were referring to port status, open could be interpreted as
available. New functions are `findAPortInUse` and `findAPortNotInUse`. Verbose,
yes.  I am open to suggestions that keep the same tense and verb usage. So, not
`findAnAvailablePort` and `findAPortInUse`, for example.

README.md

@@ -31,16 +31,16 @@ portscanner.checkPortStatus(3000, 'localhost', function(error, status) {
   console.log(status)
 })
 
-// Find the first port in use or blocked. Asynchronously checks, so first port
-// to respond is returned.
-portscanner.findAnOpenPort(3000, 3010, 'localhost', function(error, port) {
-  console.log('OPEN PORT AT ' + port)
-})
-
 // Find the first available port. Asynchronously checks, so first port
 // determined as available is returned.
-portscanner.findAClosedPort(3000, 3010, 'localhost', function(error, port) {
-  console.log('CLOSED PORT AT ' + port)
+portscanner.findAPortNotInUse(3000, 3010, 'localhost', function(error, port) {
+  console.log('AVAILABLE PORT AT: ' + port)
+})
+
+// Find the first port in use or blocked. Asynchronously checks, so first port
+// to respond is returned.
+portscanner.findAPortInUse(3000, 3010, 'localhost', function(error, port) {
+  console.log('PORT IN USE AT: ' + port)
 })
 ```
 
@@ -49,7 +49,7 @@ The example directory contains a more detailed example.
 ### To Test
 
 Bleh. I am a fan of testing, but currently looking into an easier way to test
-HTTP connections. If any ideas, please message me.
+several HTTP connections. If any ideas, please message me.
 
 ## The Future
 

example/portscan.js

@@ -22,13 +22,13 @@ setTimeout(function() {
   })
 
   // Finds a port that a service is listening on
-  portscanner.findAnOpenPort(3000, 3010, 'localhost', function(error, port) {
+  portscanner.findAPortInUse(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) {
+  // Finds a port no service is listening on
+  portscanner.findAPortNotInUse(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)

lib/portscanner.js

@@ -5,48 +5,51 @@ var portscanner = exports
 
 /**
  * Finds the first port with a status of 'open', implying the port is in use and
- * a service listening on it.
+ * there is likely 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 {Number} startPort  - Port to begin status check on (inclusive).
+ * @param {Number} endPort    - Last port to check status on (inclusive).
+ *                              Defaults to 65535.
+ * @param {String} host       - Where to scan. Defaults to 'localhost'.
  * @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.
+ *   - {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, the value is false.
  */
-portscanner.findAnOpenPort = function(startPort, endPort, host, callback) {
+portscanner.findAPortInUse = 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 {Number} startPort  - Port to begin status check on (inclusive).
+ * @param {Number} endPort    - Last port to check status on (inclusive).
+ *                              Defaults to 65535.
+ * @param {String} host       - Where to scan. Defaults to 'localhost'.
  * @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.
+ *   - {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, the value is false.
  */
-portscanner.findAClosedPort = function(startPort, endPort, host, callback) {
+portscanner.findAPortNotInUse = 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 {Number} port       - Port to check status on.
+ * @param {String} host       - Where to scan. Defaults to 'localhost'.
  * @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
+ *   - {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'