cluster: Add some docs, improve cluster.isWorker()

Fixes #1949.

doc/api/cluster.markdown

@@ -10,7 +10,7 @@ which share server ports.
     var cluster = require('cluster');
     var http = require('http');
 
-  if (!cluster.isWorker()) {
+    if (cluster.isMaster) {
       // Start the master process, fork workers.
       cluster.startMaster({ workers: 2 });
     } else {
@@ -21,11 +21,43 @@ which share server ports.
       }).listen(8000);
     }
 
-If we start it like this
+Running node will now share port 8000 between the workers:
 
-    % node cluster server.js 
+    % node server.js
-    Detected 2 cpus
     Worker 2438 online
     Worker 2437 online
 
-Node will automatically share port 8000 between the multiple instances.
+### exports.startMaster([options])
+
+  Spawns the initial worker processes, one per CPU by default.
+
+  The following options are supported:
+
+  - `filename`: script to execute in the worker process, defaults to
+    `process.argv[1]`
+  - `args`: worker program arguments, defaulting to `process.argv.slice(2)`
+  - `workers`: the number of workers, defaulting to `os.cpus().length`
+
+### exports.spawnWorker([options])
+
+   Spawn a new worker process. This is called within `cluster.startMaster()`,
+   however it is useful to implement worker resuscitation as described below
+   in the "Common patterns" section.
+
+   The `options` available are identical to `cluster.startMaster()`.
+
+## Common patterns
+
+## Worker resuscitation
+
+The following is an example of how you may implement worker resuscitation,
+spawning a new worker process when another exits.
+
+    if (cluster.isMaster) {
+      cluster.startMaster();
+      process.on('SIGCHLD', function(){
+        console.log('worker killed');
+        cluster.spawnWorker();
+      });
+    }
+

lib/cluster.js

@@ -47,14 +47,8 @@ var workerId = 0;
 var queryIds = 0;
 var queryCallbacks = {};
 
-
+exports.isWorker = 'NODE_WORKER_ID' in process.env;
-
+exports.isMaster = ! exports.isWorker;
-// Used to check if this process is a worker or not.
-// Returns boolean.
-exports.isWorker = function() {
-  return 'NODE_WORKER_ID' in process.env;
-};
-
 
 // Call this from the master process. It will start child workers.
 //