drbrain	2011-10-19 11:52:38 +0900 (Wed, 19 Oct 2011)

  New Revision: 33482

  http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=33482

  Log:
    * error.c (Init_Exception):  Document $! and $@.  Provide
      recommendations for creating exceptions for a library.

  Modified files:
    trunk/ChangeLog
    trunk/error.c

Index: ChangeLog
===================================================================
--- ChangeLog	(revision 33481)
+++ ChangeLog	(revision 33482)
@@ -1,3 +1,8 @@
+Wed Oct 19 11:48:44 2011  Eric Hodel  <drbrain@s...>
+
+	* error.c (Init_Exception):  Document $! and $@.  Provide
+	  recommendations for creating exceptions for a library.
+
 Wed Oct 19 11:25:46 2011  Eric Hodel  <drbrain@s...>
 
 	* error.c (Init_Exception):  Add hierarchy of Exception subclasses.
Index: error.c
===================================================================
--- error.c	(revision 33481)
+++ error.c	(revision 33482)
@@ -1522,15 +1522,45 @@
  */
 
 /*
- *  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:
  *
  *  * NoMemoryError

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/