Update documentation for Exception [ci skip]

Mostly from burdettelamar@yahoo.com (Burdette Lamar).

Implements [Misc #16156]

1 files changed, 36 insertions, 20 deletions

diff --git a/error.c b/error.c
index 2089c3787e..87357a4ebe 100644
--- a/error.c
+++ b/error.c
@@ -2387,32 +2387,46 @@ syserr_eqq(VALUE self, VALUE exc)
  */
 
 /*
- *  Descendants of class Exception are used to communicate between
+ *  \Class Exception and its subclasses are used to communicate between
  *  Kernel#raise and +rescue+ statements in <code>begin ... end</code> blocks.
- *  Exception objects carry information about the exception -- its type (the
- *  exception's class name), an optional descriptive string, and optional
- *  traceback information.  Exception subclasses may add additional
- *  information like NameError#name.
  *
- *  Programs may make subclasses of Exception, typically of StandardError or
- *  RuntimeError, to provide custom classes and add additional information.
- *  See the subclass list below for defaults for +raise+ and +rescue+.
+ *  An Exception object carries information about an exception:
+ *  - Its type (the exception's class).
+ *  - An optional descriptive message.
+ *  - Optional backtrace information.
+ *
+ *  Some built-in subclasses of Exception have additional methods: e.g., NameError#name.
+ *
+ *  == Defaults
+ *
+ *  Two Ruby statements have default exception classes:
+ *  - +raise+: defaults to RuntimeError.
+ *  - +rescue+: defaults to StandardError.
+ *
+ *  == Global Variables
  *
  *  When an exception has been raised but not yet handled (in +rescue+,
- *  +ensure+, +at_exit+ and +END+ blocks) the global variable <code>$!</code>
- *  will contain the current exception and <code>$@</code> contains the
- *  current exception's backtrace.
+ *  +ensure+, +at_exit+ and +END+ blocks), two global variables are set:
+ *  - <code>$!</code> contains the current exception.
+ *  - <code>$@</code> contains its backtrace.
  *
- *  It is recommended that a library should have one subclass of StandardError
- *  or RuntimeError and have specific exception types inherit from it.  This
- *  allows the user to rescue a generic exception type to catch all exceptions
+ *  == Custom Exceptions
+ *
+ *  To provide additional or alternate information,
+ *  a program may create custom exception classes
+ *  that derive from the built-in exception classes.
+ *
+ *  A good practice is for a library to create a single "generic" exception class
+ *  (typically a subclass of StandardError or RuntimeError)
+ *  and have its other exception classes derive from that class.
+ *  This allows the user to rescue the generic exception, thus catching all exceptions
  *  the library may raise even if future versions of the library add new
  *  exception subclasses.
  *
  *  For example:
  *
  *    class MyLibrary
- *      class Error < RuntimeError
+ *      class Error < ::StandardError
  *      end
  *
  *      class WidgetError < Error
@@ -2423,8 +2437,10 @@ syserr_eqq(VALUE self, VALUE exc)
  *
  *    end
  *
- *  To handle both WidgetError and FrobError the library user can rescue
- *  MyLibrary::Error.
+ *  To handle both MyLibrary::WidgetError and MyLibrary::FrobError the library
+ *  user can rescue MyLibrary::Error.
+ *
+ *  == Built-In Exception Classes
  *
  *  The built-in subclasses of Exception are:
  *
@@ -2436,7 +2452,7 @@ syserr_eqq(VALUE self, VALUE exc)
  *  * SecurityError
  *  * SignalException
  *    * Interrupt
- *  * StandardError -- default for +rescue+
+ *  * StandardError
  *    * ArgumentError
  *      * UncaughtThrowError
  *    * EncodingError
@@ -2453,7 +2469,7 @@ syserr_eqq(VALUE self, VALUE exc)
  *    * RangeError
  *      * FloatDomainError
  *    * RegexpError
- *    * RuntimeError -- default for +raise+
+ *    * RuntimeError
  *      * FrozenError
  *    * SystemCallError
  *      * Errno::*
@@ -2462,7 +2478,7 @@ syserr_eqq(VALUE self, VALUE exc)
  *    * ZeroDivisionError
  *  * SystemExit
  *  * SystemStackError
- *  * fatal -- impossible to rescue
+ *  * fatal
  */
 
 void