diff --git a/ChangeLog b/ChangeLog
index 56f81c3355..35dda9aa55 100644
--- a/ChangeLog
+++ b/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.
diff --git a/error.c b/error.c
index f699ea7bdd..600be018fe 100644
--- a/error.c
+++ b/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:
  *