diff options
author | Jeremy Evans <code@jeremyevans.net> | 2019-09-09 15:20:54 -0700 |
---|---|---|
committer | Jeremy Evans <code@jeremyevans.net> | 2019-09-09 15:23:26 -0700 |
commit | 00744a03d576f308d7fa586c2d04b5c1cb8fe3f4 (patch) | |
tree | 41fe552c846e10eeddcf1aefaa99d18880124641 | |
parent | d8a4af47a5e5f72be2cd2897712d1718013b2e4c (diff) | |
download | ruby-00744a03d576f308d7fa586c2d04b5c1cb8fe3f4.tar.gz |
Update documentation for Exception [ci skip]
Mostly from burdettelamar@yahoo.com (Burdette Lamar).
Implements [Misc #16156]
-rw-r--r-- | error.c | 56 |
1 files changed, 36 insertions, 20 deletions
@@ -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 |