doc: improve unhandledException doc copy

Rework the doc a bit to tighten it up, including removing the
use of `you`

Fix some line wrapping issues.

PR-URL: https://github.com/nodejs/node/pull/5287
Reviewed-By: Roman Klauke <romaaan.git@gmail.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
...

diff --git a/doc/api/process.markdown b/doc/api/process.markdown
index 6027cf4..c243b0f 100644 (file)
--- a/doc/api/process.markdown
+++ b/doc/api/process.markdown
@@ -7,12 +7,13 @@ It is an instance of [`EventEmitter`][].
 
 ## Event: 'beforeExit'
 
-This event is emitted when Node.js empties its event loop and has nothing else to
-schedule. Normally, Node.js exits when there is no work scheduled, but a listener
-for `'beforeExit'` can make asynchronous calls, and cause Node.js to continue.
+This event is emitted when Node.js empties its event loop and has nothing else
+to schedule. Normally, Node.js exits when there is no work scheduled, but a
+listener for `'beforeExit'` can make asynchronous calls, and cause Node.js to
+continue.
 
-`'beforeExit'` is not emitted for conditions causing explicit termination, such as
-[`process.exit()`][] or uncaught exceptions, and should not be used as an
+`'beforeExit'` is not emitted for conditions causing explicit termination, such
+as [`process.exit()`][] or uncaught exceptions, and should not be used as an
 alternative to the `'exit'` event unless the intention is to schedule more work.
 
 ## Event: 'exit'
@@ -91,11 +92,12 @@ indefinitely) or upon process exit (more convenient for scripts).
 
 ## Event: 'uncaughtException'
 
-Emitted when an exception bubbles all the way back to the event loop. If a
-listener is added for this exception, the default action (which is to print
-a stack trace and exit) will not occur.
+The `'uncaughtException'` event is emitted when an exception bubbles all the
+way back to the event loop. By default, Node.js handles such exceptions by
+printing the stack trace to stderr and exiting. Adding a handler for the
+`'uncaughtException'` event overrides this default behavior.
 
-Example of listening for `'uncaughtException'`:
+For example:
 
 ```js
 process.on('uncaughtException', (err) => {
@@ -111,26 +113,27 @@ nonexistentFunc();
 console.log('This will not run.');
 ```
 
-Note that `'uncaughtException'` is a very crude mechanism for exception
-handling.
+### Warning: Using `'uncaughtException'` correctly
 
-Do *not* use it as the Node.js equivalent of `On Error Resume Next`. An
-unhandled exception means your application - and by extension Node.js itself -
-is in an undefined state. Blindly resuming means *anything* could happen.
+Note that `'uncaughtException'` is a crude mechanism for exception handling
+intended to be used only as a last resort. The event *should not* be used as
+an equivalent to `On Error Resume Next`. Unhandled exceptions inherently mean
+that an application is in an undefined state. Attempting to resume application
+code without properly recovering from the exception can cause additional
+unforeseen and unpredictable issues.
 
 Exceptions thrown from within the event handler will not be caught. Instead the
 process will exit with a non zero exit code and the stack trace will be printed.
 This is to avoid infinite recursion.
 
-Think of resuming as pulling the power cord when you are upgrading your system.
-Nine out of ten times nothing happens - but the 10th time, your system is bust.
+Attempting to resume normally after an uncaught exception can be similar to
+pulling out of the power cord when upgrading a computer -- nine out of ten
+times nothing happens - but the 10th time, the system becomes corrupted.
 
-`'uncaughtException'` should be used to perform synchronous cleanup before
-shutting down the process. It is not safe to resume normal operation after
-`'uncaughtException'`. If you do use it, restart your application after every
-unhandled exception!
-
-You have been warned.
+The correct use of `'uncaughtException'` is to perform synchronous cleanup
+of allocated resources (e.g. file descriptors, handles, etc) before shutting
+down the process. It is not safe to resume normal operation after
+`'uncaughtException'`.
 
 ## Event: 'unhandledRejection'
 
@@ -142,8 +145,8 @@ a promise chain. This event is useful for detecting and keeping track of
 promises that were rejected whose rejections were not handled yet. This event
 is emitted with the following arguments:
 
- - `reason` the object with which the promise was rejected (usually an [`Error`][]
-instance).
+ - `reason` the object with which the promise was rejected (usually an
+   [`Error`][] instance).
  - `p` the promise that was rejected.
 
 Here is an example that logs every unhandled rejection to the console
@@ -254,10 +257,10 @@ Note:
 
 - `SIGUSR1` is reserved by Node.js to start the debugger.  It's possible to
   install a listener but that won't stop the debugger from starting.
-- `SIGTERM` and `SIGINT` have default handlers on non-Windows platforms that resets
-  the terminal mode before exiting with code `128 + signal number`. If one of
-  these signals has a listener installed, its default behavior will be removed
-  (Node.js will no longer exit).
+- `SIGTERM` and `SIGINT` have default handlers on non-Windows platforms that
+  resets the terminal mode before exiting with code `128 + signal number`. If
+  one of these signals has a listener installed, its default behavior will be
+  removed (Node.js will no longer exit).
 - `SIGPIPE` is ignored by default. It can have a listener installed.
 - `SIGHUP` is generated on Windows when the console window is closed, and on other
   platforms under various similar conditions, see signal(7). It can have a
@@ -269,11 +272,12 @@ Note:
 - `SIGINT` from the terminal is supported on all platforms, and can usually be
   generated with `CTRL+C` (though this may be configurable). It is not generated
   when terminal raw mode is enabled.
-- `SIGBREAK` is delivered on Windows when `CTRL+BREAK` is pressed, on non-Windows
+- `SIGBREAK` is delivered on Windows when `CTRL+BREAK` is pressed, on
+  non-Windows
   platforms it can be listened on, but there is no way to send or generate it.
-- `SIGWINCH` is delivered when the console has been resized. On Windows, this will
-  only happen on write to the console when the cursor is being moved, or when a
-  readable tty is used in raw mode.
+- `SIGWINCH` is delivered when the console has been resized. On Windows, this
+  will only happen on write to the console when the cursor is being moved, or
+  when a readable tty is used in raw mode.
 - `SIGKILL` cannot have a listener installed, it will unconditionally terminate
   Node.js on all platforms.
 - `SIGSTOP` cannot have a listener installed.