* 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

ChangeLog

@@ -1,3 +1,8 @@
+Wed Oct 19 11:48:44 2011  Eric Hodel  <drbrain@segment7.net>
+
+	* error.c (Init_Exception):  Document $! and $@.  Provide
+	  recommendations for creating exceptions for a library.
+
 Wed Oct 19 11:25:46 2011  Eric Hodel  <drbrain@segment7.net>
 
 	* error.c (Init_Exception):  Add hierarchy of Exception subclasses.

error.c

@@ -1522,14 +1522,44 @@ syserr_eqq(VALUE self, VALUE exc)
  */
 
 /*
- *  Descendants of class <code>Exception</code> are used to communicate
+ *  Descendants of class Exception are used to communicate between
- *  between <code>raise</code> methods and <code>rescue</code>
+ *  Kernel#raise and +rescue+ statements in <code>begin ... end</code> blocks.
- *  statements in <code>begin/end</code> blocks. <code>Exception</code>
+ *  Exception objects carry information about the exception -- its type (the
- *  objects carry information about the exception---its type (the
+ *  exception's class name), an optional descriptive string, and optional
- *  exception's class name), an optional descriptive string, and
+ *  traceback information.  Exception subclasses may add additional
- *  optional traceback information. Programs may subclass
+ *  information like NameError#name.
- *  <code>Exception</code>, or more typically <code>StandardError</code>
+ *
- *  to provide custom classes and add additional information.
+ *  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:
  *