From f442904a2745ba2fc57217d750f0604899525c83 Mon Sep 17 00:00:00 2001
From: Sam Roberts <sam@strongloop.com>
Date: Sun, 14 Jun 2015 19:06:22 -0700
Subject: [PATCH] doc: describe process API for IPC

Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
PR-URL: https://github.com/nodejs/node/pull/1978
---
 doc/api/child_process.markdown |  9 ++++---
 doc/api/cluster.markdown       |  4 ++-
 doc/api/process.markdown       | 45 ++++++++++++++++++++++++++++++++++
 3 files changed, 54 insertions(+), 4 deletions(-)

diff --git a/doc/api/child_process.markdown b/doc/api/child_process.markdown
index 31ac72451d5e1b..a5ac5fe9b3decf 100644
--- a/doc/api/child_process.markdown
+++ b/doc/api/child_process.markdown
@@ -46,7 +46,7 @@ you are listening on both events to fire a function, remember to guard against
 calling your function twice.
 
 See also [`ChildProcess#kill()`](#child_process_child_kill_signal) and
-[`ChildProcess#send()`](#child_process_child_send_message_sendhandle).
+[`ChildProcess#send()`](#child_process_child_send_message_sendhandle_callback).
 
 ### Event:  'exit'
 
@@ -85,8 +85,9 @@ and the `.connected` property is false.
 
 ### Event: 'message'
 
-* `message` {Object} a parsed JSON object or primitive value
-* `sendHandle` {Handle object} a Socket or Server object
+* `message` {Object} a parsed JSON object or primitive value.
+* `sendHandle` {Handle object} a [net.Socket][] or [net.Server][] object, or
+  undefined.
 
 Messages sent by `.send(message, [sendHandle])` are obtained using the
 `message` event.
@@ -760,3 +761,5 @@ throw.  The `Error` object will contain the entire result from
 [`child_process.spawnSync`](#child_process_child_process_spawnsync_command_args_options)
 
 [EventEmitter]: events.html#events_class_events_eventemitter
+[net.Server]: net.html#net_class_net_server
+[net.Socket]: net.html#net_class_net_socket
diff --git a/doc/api/cluster.markdown b/doc/api/cluster.markdown
index d29d5973d85540..c46a2cc5385a8e 100644
--- a/doc/api/cluster.markdown
+++ b/doc/api/cluster.markdown
@@ -436,7 +436,7 @@ exit, the master may choose not to respawn a worker based on this value.
 Send a message to a worker or master, optionally with a handle.
 
 In the master this sends a message to a specific worker. It is identical to
-[child.send()](child_process.html#child_process_child_send_message_sendhandle).
+[ChildProcess.send()][].
 
 In a worker this sends a message to the master. It is identical to
 `process.send()`.
@@ -646,3 +646,5 @@ Similar to the `cluster.on('exit')` event, but specific to this worker.
 This event is the same as the one provided by `child_process.fork()`.
 
 In a worker you can also use `process.on('error')`.
+
+[ChildProcess.send()]: child_process.html#child_process_child_send_message_sendhandle_callback
diff --git a/doc/api/process.markdown b/doc/api/process.markdown
index 7d3fc8de0ac64a..427792d7dbd131 100644
--- a/doc/api/process.markdown
+++ b/doc/api/process.markdown
@@ -70,6 +70,16 @@ Example of listening for `exit`:
     });
 
 
+## Event: 'message'
+
+* `message` {Object} a parsed JSON object or primitive value
+* `sendHandle` {Handle object} a [net.Socket][] or [net.Server][] object, or
+  undefined.
+
+Messages sent by [ChildProcess.send()][] are obtained using the `'message'`
+event on the child's process object.
+
+
 ## Event: 'beforeExit'
 
 This event is emitted when Node.js empties its event loop and has nothing else to
@@ -904,6 +914,38 @@ a diff reading, useful for benchmarks and measuring intervals:
     }, 1000);
 
 
+## process.send(message[, sendHandle][, callback])
+
+* `message` {Object}
+* `sendHandle` {Handle object}
+
+When Node.js is spawned with an IPC channel attached, it can send messages to its
+parent process using `process.send()`. Each will be received as a
+['message'](child_process.html#child_process_event_message)
+event on the parent's `ChildProcess` object.
+
+If io.js was not spawned with an IPC channel, `process.send()` will be undefined.
+
+
+## process.disconnect()
+
+Close the IPC channel to the parent process, allowing this child to exit
+gracefully once there are no other connections keeping it alive.
+
+Identical to the parent process's
+[ChildProcess.disconnect()](child_process.html#child_process_child_disconnect).
+
+If io.js was not spawned with an IPC channel, `process.disconnect()` will be
+undefined.
+
+
+### process.connected
+
+* {Boolean} Set to false after `process.disconnect()` is called
+
+If `process.connected` is false, it is no longer possible to send messages.
+
+
 ## process.mainModule
 
 Alternate way to retrieve
@@ -915,4 +957,7 @@ to the same module.
 
 As with `require.main`, it will be `undefined` if there was no entry script.
 
+[ChildProcess.send()]: child_process.html#child_process_child_send_message_sendhandle_callback
 [EventEmitter]: events.html#events_class_events_eventemitter
+[net.Server]: net.html#net_class_net_server
+[net.Socket]: net.html#net_class_net_socket