From 72d29e6afdedab3440f3f028c59c018fe35f501e Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Wed, 17 Feb 2016 11:10:46 -0800
Subject: [PATCH] doc: improve unhandledException doc copy

Rework the doc a bit to tighten it up, including removing the
use of `you`
---
 doc/api/process.markdown | 35 ++++++++++++++++++-----------------
 1 file changed, 18 insertions(+), 17 deletions(-)

diff --git a/doc/api/process.markdown b/doc/api/process.markdown
index ca2971328025c5..2f20f730d36e66 100644
--- a/doc/api/process.markdown
+++ b/doc/api/process.markdown
@@ -91,11 +91,11 @@ 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 +111,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'