doc: expand documentation for process.exit()

The fact that process.exit() interrupts pending async operations
such as non-blocking i/o is becoming a bit more pronounced with
the recent libuv update. This commit expands the documentation
for `process.exit()` to explain clearly how it affects async
operations.

PR-URL: #6410
Reviewed-By: Сковорода Никита Андреевич <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Robert Lindstaedt <[email protected]>

Author: jasnell

doc/api/process.md

@@ -729,26 +729,73 @@ Example:
 
 ## process.exit([code])
 
-Ends the process with the specified `code`.  If omitted, exit uses the
-'success' code `0`.
+* `code` {Integer} The exit code. Defaults to `0`.
+
+The `process.exit()` method instructs Node.js to terminate the process as
+quickly as possible with the specified exit `code`. If the `code` is omitted, 
+exit uses either the 'success' code `0` or the value of `process.exitCode` if
+specified.
 
 To exit with a 'failure' code:
 
 ```js
 process.exit(1);
 ```
 
-The shell that executed Node.js should see the exit code as 1.
+The shell that executed Node.js should see the exit code as `1`.
+
+It is important to note that calling `process.exit()` will force the process to
+exit as quickly as possible *even if there are still asynchronous operations 
+pending* that have not yet completed fully, *including* I/O operations to
+`process.stdout` and `process.stderr`.
+
+In most situations, it is not actually necessary to call `process.exit()`
+explicitly. The Node.js process will exit on it's own *if there is no additional
+work pending* in the event loop. The `process.exitCode` property can be set to
+tell the process which exit code to use when the process exits gracefully.
+
+For instance, the following example illustrates a *misuse* of the 
+`process.exit()` method that could lead to data printed to stdout being 
+truncated and lost:
+
+```js
+// This is an example of what *not* to do:
+if (someConditionNotMet()) {
+  printUsageToStdout();
+  process.exit(1);
+}
+```
+
+The reason this is problematic is because writes to `process.stdout` in Node.js
+are *non-blocking* and may occur over multiple ticks of the Node.js event loop.
+Calling `process.exit()`, however, forces the process to exit *before* those
+additional writes to `stdout` can be performed.
+
+Rather than calling `process.exit()` directly, the code *should* set the
+`process.exitCode` and allow the process to exit naturally by avoiding
+scheduling any additional work for the event loop:
+
+```js
+// How to properly set the exit code while letting
+// the process exit gracefully.
+if (someConditionNotMet()) {
+  printUsageToStdout();
+  process.exitCode = 1;
+}
+```
 
+If it is necessary to terminate the Node.js process due to an error condition,
+throwing an *uncaught* error and allowing the process to terminate accordingly
+is safer than calling `process.exit()`.
 
 ## process.exitCode
 
 A number which will be the process exit code, when the process either
 exits gracefully, or is exited via [`process.exit()`][] without specifying
 a code.
 
-Specifying a code to [`process.exit(code)`][`process.exit()`] will override any previous
-setting of `process.exitCode`.
+Specifying a code to [`process.exit(code)`][`process.exit()`] will override any 
+previous setting of `process.exitCode`.
 
 
 ## process.getegid()