|
diff --git a/error.c b/error.c
|
|
index 2089c3787e..90c412af14 100644
|
|
--- a/error.c
|
|
+++ b/error.c
|
|
@@ -2387,25 +2387,39 @@ 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 name).
|
|
+ * - An optional descriptive string.
|
|
+ * - 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.
|
|
*
|
|
@@ -2426,6 +2440,8 @@ syserr_eqq(VALUE self, VALUE exc)
|
|
* To handle both WidgetError and FrobError the library user can rescue
|
|
* MyLibrary::Error.
|
|
*
|
|
+ * == Built-In Exception Classes
|
|
+ *
|
|
* The built-in subclasses of Exception are:
|
|
*
|
|
* * NoMemoryError
|
|
@@ -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::*
|