Browse files

* 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
  • Loading branch information...
1 parent 62bd3dd commit 34fb36422d4eb024d9c55095bffe2f19b248c893 @drbrain drbrain committed Oct 19, 2011
Showing with 43 additions and 8 deletions.
  1. +5 −0 ChangeLog
  2. +38 −8 error.c
View
5 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.
View
46 error.c
@@ -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:
*

0 comments on commit 34fb364

Please sign in to comment.