#10856: document (Base)Exception.args better.

1 files changed, 26 insertions, 12 deletions

diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index bf7be21..528febd 100644
--- a/Doc/library/exceptions.rst
+++ b/Doc/library/exceptions.rst
@@ -18,12 +18,10 @@ equivalent, even if they have the same name.
 
 The built-in exceptions listed below can be generated by the interpreter or
 built-in functions.  Except where mentioned, they have an "associated value"
-indicating the detailed cause of the error. This may be a string or a tuple
-containing several items of information (e.g., an error code and a string
-explaining the code).  The associated value is usually passed to the exception
-class's constructor.  If the exception class is derived from the standard root
-class :exc:`BaseException`, the associated value is present as the exception
-instance's :attr:`args` attribute.
+indicating the detailed cause of the error.  This may be a string or a tuple of
+several items of information (e.g., an error code and a string explaining the
+code).  The associated value is usually passed as arguments to the exception
+class's constructor.
 
 User code can raise built-in exceptions.  This can be used to test an exception
 handler or to report an error condition "just like" the situation in which the
@@ -38,16 +36,32 @@ defining exceptions is available in the Python Tutorial under
 
 The following exceptions are used mostly as base classes for other exceptions.
 
-.. XXX document with_traceback()
-
 .. exception:: BaseException
 
    The base class for all built-in exceptions.  It is not meant to be directly
-   inherited by user-defined classes (for that use :exc:`Exception`).  If
+   inherited by user-defined classes (for that, use :exc:`Exception`).  If
    :func:`bytes` or :func:`str` is called on an instance of this class, the
-   representation of the argument(s) to the instance are returned or the empty
-   string when there were no arguments.  All arguments are  stored in :attr:`args`
-   as a tuple.
+   representation of the argument(s) to the instance are returned, or the empty
+   string when there were no arguments.
+
+   .. attribute:: args
+
+      The tuple of arguments given to the exception constructor.  Some built-in
+      exceptions (like :exc:`IOError`) expect a certain number of arguments and
+      assign a special meaning to the elements of this tuple, while others are
+      usually called only with a single string giving an error message.
+
+   .. method:: with_traceback(tb)
+
+      This method sets *tb* as the new traceback for the exception and returns
+      the exception object.  It is usually used in exception handling code like
+      this::
+
+         try:
+             ...
+         except SomeException:
+             tb = sys.exc_info()[2]
+             raise OtherException(...).with_traceback(tb)
 
 
 .. exception:: Exception