diff options
author | drbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2011-10-19 02:52:38 +0000 |
---|---|---|
committer | drbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2011-10-19 02:52:38 +0000 |
commit | 34fb36422d4eb024d9c55095bffe2f19b248c893 (patch) | |
tree | 17894d1c0480427e98586a7842265530b8874a08 /error.c | |
parent | 62bd3dd4af5ac017a05e250293abe9e5c87a1193 (diff) | |
download | ruby-34fb36422d4eb024d9c55095bffe2f19b248c893.tar.gz |
* error.c (Init_Exception): Document $! and $@. Provide
recommendations for creating exceptions for a library.
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@33482 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'error.c')
-rw-r--r-- | error.c | 46 |
1 files changed, 38 insertions, 8 deletions
@@ -1522,14 +1522,44 @@ syserr_eqq(VALUE self, VALUE exc) */ /* - * Descendants of class <code>Exception</code> are used to communicate - * between <code>raise</code> methods and <code>rescue</code> - * statements in <code>begin/end</code> blocks. <code>Exception</code> - * objects carry information about the exception---its type (the - * exception's class name), an optional descriptive string, and - * optional traceback information. Programs may subclass - * <code>Exception</code>, or more typically <code>StandardError</code> - * to provide custom classes and add additional information. + * Descendants of class Exception 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+. + * + * 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. + * + * 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 + * the library may raise even if future versions of the library add new + * exception subclasses. + * + * For example: + * + * class MyLibrary + * class Error < RuntimeError + * end + * + * class WidgetError < Error + * end + * + * class FrobError < Error + * end + * + * end + * + * To handle both WidgetError and FrobError the library user can rescue + * MyLibrary::Error. * * The built-in subclasses of Exception are: * |