Improve child process stdio documentation

1 files changed, 25 insertions, 16 deletions

diff --git a/doc/api/child_process.markdown b/doc/api/child_process.markdown
index e9aab649f..72597a41c 100644
--- a/doc/api/child_process.markdown
+++ b/doc/api/child_process.markdown
@@ -340,22 +340,31 @@ API.
 The 'stdio' option to `child_process.spawn()` is an array where each
 index corresponds to a fd in the child.  The value is one of the following:
 
-1. `null`, `undefined` - Use default value. For 0,1,2 stdios this is the same
-   as `'pipe'`. For any higher value, `'ignore'`
-2. `'ignore'` - Open the fd in the child, but do not expose it to the parent
-3. `'pipe'` - Open the fd and expose as a `Stream` object to parent.
-4. `'ipc'` - Create IPC channel for passing messages/file descriptors between
-   parent and child.
-
-     Note: A ChildProcess may have at most *one* IPC stdio file descriptor.
-     Setting this option enables the ChildProcess.send() method.  If the
-     child writes JSON messages to this file descriptor, then this will trigger
-     ChildProcess.on('message').  If the child is a Node.js program, then
-     the presence of an IPC channel will enable process.send() and
-     process.on('message')
-5. positive integer - Share corresponding fd with child
-6. Any TTY, TCP, File stream (or any object with `fd` property) - Share
-   corresponding stream with child.
+1. `'pipe'` - Create a pipe between the child process and the parent process.
+   The parent end of the pipe is exposed to the parent as a property on the
+   child_process object as `ChildProcess.stdio[fd]`. Pipes created for
+   fds 0 - 2 are also available as ChildProcess.stdin, ChildProcess.stdout
+   and ChildProcess.stderr, respectively.
+2. `'ipc'` - Create an IPC channel for passing messages/file descriptors
+   between parent and child. A ChildProcess may have at most *one* IPC stdio
+   file descriptor. Setting this option enables the ChildProcess.send() method.
+   If the child writes JSON messages to this file descriptor, then this will
+   trigger ChildProcess.on('message').  If the child is a Node.js program, then
+   the presence of an IPC channel will enable process.send() and
+   process.on('message').
+3. `'ignore'` - Do not set this file descriptor in the child. Note that Node
+   will always open fd 0 - 2 for the processes it spawns. When any of these is
+   ignored node will open `/dev/null` and attach it to the child's fd.
+4. `Stream` object - Share a readable or writable stream that refers to a tty,
+   file, socket, or a pipe with the child process. The stream's underlying
+   file descriptor is duplicated in the child process to the fd that 
+   corresponds to the index in the `stdio` array.
+5. Positive integer - The integer value is interpreted as a file descriptor 
+   that is is currently open in the parent process. It is shared with the child
+   process, similar to how `Stream` objects can be shared.
+6. `null`, `undefined` - Use default value. For stdio fds 0, 1 and 2 (in other
+   words, stdin, stdout, and stderr) a pipe is created. For fd 3 and up, the
+   default is `'ignore'`.
 
 As a shorthand, the `stdio` argument may also be one of the following
 strings, rather than an array: