doc: child_process corrections and cleanups

- Make explicit that .disconnected is set before the disconnect event,
  and it is not allowed to send messages after calling .disconnect(),
  even while waiting for a delayed disconect event.
- Remove obsolete claim that explicit exit is required
- Describe silent: in the options for fork()
- Describe .connected as the property it is, not just as an aside in
  the disconnect() method

1 files changed, 25 insertions, 19 deletions

diff --git a/doc/api/child_process.markdown b/doc/api/child_process.markdown
index 846649429a..d21f7db3e6 100644
--- a/doc/api/child_process.markdown
+++ b/doc/api/child_process.markdown
@@ -52,6 +52,9 @@ of the signal, otherwise `null`.
 
 Note that the child process stdio streams might still be open.
 
+Also, note that node establishes signal handlers for `'SIGINT'` and `'SIGTERM`',
+so it will not terminate due to receipt of those signals, it will exit.
+
 See `waitpid(2)`.
 
 ### Event: 'close'
@@ -66,10 +69,9 @@ might share the same stdio streams.
 
 ### Event: 'disconnect'
 
-This event is emitted after using the `.disconnect()` method in the parent or
-in the child. After disconnecting it is no longer possible to send messages.
-An alternative way to check if you can send messages is to see if the
-`child.connected` property is `true`.
+This event is emitted after calling the `.disconnect()` method in the parent
+or in the child. After disconnecting it is no longer possible to send messages,
+and the `.connected` property is false.
 
 ### Event: 'message'
 
@@ -121,6 +123,12 @@ Example:
     console.log('Spawned child pid: ' + grep.pid);
     grep.stdin.end();
 
+### child.connected
+
+* {Boolean} Set to false after `.disconnect' is called
+
+If `.connected` is false, it is no longer possible to send messages.
+
 ### child.kill([signal])
 
 * `signal` {String}
@@ -265,12 +273,15 @@ It is also recommended not to use `.maxConnections` in this condition.
 
 ### child.disconnect()
 
-To close the IPC connection between parent and child use the
-`child.disconnect()` method. This allows the child to exit gracefully since
-there is no IPC channel keeping it alive. When calling this method the
-`disconnect` event will be emitted in both parent and child, and the
-`connected` flag will be set to `false`. Please note that you can also call
-`process.disconnect()` in the child process.
+Close the IPC channel between parent and child, allowing the child to exit
+gracefully once there are no other connections keeping it alive. After calling
+this method the `.connected` flag will be set to `false` in both the parent and
+child, and it is no longer possible to send messages.
+
+The 'disconnect' event will be emitted when there are no messages in the process
+of being received, most likely immediately.
+
+Note that you can also call `process.disconnect()` in the child process.
 
 ## child_process.spawn(command, [args], [options])
 
@@ -465,7 +476,7 @@ See also: `child_process.exec()` and `child_process.fork()`
   * `env` {Object} Environment key-value pairs
   * `encoding` {String} (Default: 'utf8')
   * `timeout` {Number} (Default: 0)
-  * `maxBuffer` {Number} (Default: 200*1024)
+  * `maxBuffer` {Number} (Default: `200*1024`)
   * `killSignal` {String} (Default: 'SIGTERM')
 * `callback` {Function} called with the output when process terminates
   * `error` {Error}
@@ -531,7 +542,7 @@ subshell but rather the specified file directly. This makes it slightly
 leaner than `child_process.exec`. It has the same options.
 
 
-## child\_process.fork(modulePath, [args], [options])
+## child_process.fork(modulePath, [args], [options])
 
 * `modulePath` {String} The module to run in the child
 * `args` {Array} List of string arguments
@@ -540,6 +551,8 @@ leaner than `child_process.exec`. It has the same options.
   * `env` {Object} Environment key-value pairs
   * `encoding` {String} (Default: 'utf8')
   * `execPath` {String} Executable used to create the child process
+  * `silent` {Boolean} If true, prevent stdout and stderr in the spawned node
+    process from being associated with the parent's (default is false)
 * Return: ChildProcess object
 
 This is a special case of the `spawn()` functionality for spawning Node
@@ -547,13 +560,6 @@ processes. In addition to having all the methods in a normal ChildProcess
 instance, the returned object has a communication channel built-in. See
 `child.send(message, [sendHandle])` for details.
 
-By default the spawned Node process will have the stdout, stderr associated
-with the parent's. To change this behavior set the `silent` property in the
-`options` object to `true`.
-
-The child process does not automatically exit once it's done, you need to call
-`process.exit()` explicitly. This limitation may be lifted in the future.
-
 These child Nodes are still whole new instances of V8. Assume at least 30ms
 startup and 10mb memory for each new Node. That is, you cannot create many
 thousands of them.