Index: libunittest.tex
===================================================================
--- libunittest.tex	(revision 51654)
+++ libunittest.tex	(working copy)
@@ -462,7 +462,7 @@
 \subsection{Classes and functions
             \label{unittest-contents}}
 
-\begin{classdesc}{TestCase}{}
+\begin{classdesc}{TestCase}{\optional{methodName}}
   Instances of the \class{TestCase} class represent the smallest
   testable units in the \module{unittest} universe.  This class is
   intended to be used as a base class, with specific tests being
@@ -470,6 +470,23 @@
   interface needed by the test runner to allow it to drive the
   test, and methods that the test code can use to check for and
   report various kinds of failure.
+  
+  Each instance of \class{TestCase} will run a single test method:
+  the method named \var{methodName}.  If you remember, we had an
+  earlier example that went something like this:
+  
+  \begin{verbatim}
+  def suite():
+      suite = unittest.TestSuite()
+      suite.addTest(WidgetTestCase("testDefaultSize"))
+      suite.addTest(WidgetTestCase("testResize"))
+      return suite
+  \end{verbatim}
+  
+  Here, we create two instances of \class{WidgetTestCase}, each of
+  which runs a single test.
+  
+  \var{methodName} defaults to \code{"runTest"}.
 \end{classdesc}
 
 \begin{classdesc}{FunctionTestCase}{testFunc\optional{,
@@ -502,6 +519,11 @@
   subclass.
 \end{classdesc}
 
+\begin{classdesc}{TestResult}{}
+  This class is used to compile information about which tests have succeeded
+  and which have failed.
+\end{classdesc}
+
 \begin{datadesc}{defaultTestLoader}
   Instance of the \class{TestLoader} class intended to be shared.  If no
   customization of the \class{TestLoader} is needed, this instance can
@@ -574,8 +596,9 @@
 \begin{methoddesc}[TestCase]{run}{\optional{result}}
   Run the test, collecting the result into the test result object
   passed as \var{result}.  If \var{result} is omitted or \constant{None},
-  a temporary result object is created and used, but is not made
-  available to the caller.
+  a temporary result object is created (by calling the
+  \method{defaultTestCase()} method) and used; this result object is not
+  returned to \method{run()}'s caller.
   
   The same effect may be had by simply calling the \class{TestCase}
   instance.
@@ -684,8 +707,13 @@
 \end{methoddesc}
 
 \begin{methoddesc}[TestCase]{defaultTestResult}{}
-  Return the default type of test result object to be used to run this
-  test.
+  Return an instance of the test result class that should be used
+  for this test case class (if no other result instance is provided
+  to the \method{run()} method.
+  
+  For \class{TestCase} instances, this will always be an instance of
+  \class{unittest.TestResult};  subclasses of \class{TestCase} should
+  override this as necessary.
 \end{methoddesc}
 
 \begin{methoddesc}[TestCase]{id}{}
@@ -761,26 +789,20 @@
 tests for reporting purposes; a \class{TestResult} instance is
 returned by the \method{TestRunner.run()} method for this purpose.
 
-Each instance holds the total number of tests run, and collections of
-failures and errors that occurred among those test runs.  The
-collections contain tuples of \code{(\var{testcase},
-\var{traceback})}, where \var{traceback} is a string containing a
-formatted version of the traceback for the exception.
-
 \class{TestResult} instances have the following attributes that will
 be of interest when inspecting the results of running a set of tests:
 
 \begin{memberdesc}[TestResult]{errors}
   A list containing 2-tuples of \class{TestCase} instances and
-  formatted tracebacks. Each tuple represents a test which raised an
-  unexpected exception.
+  strings holding formatted tracebacks. Each tuple represents a test which
+  raised an unexpected exception.
   \versionchanged[Contains formatted tracebacks instead of
                   \function{sys.exc_info()} results]{2.2}
 \end{memberdesc}
 
 \begin{memberdesc}[TestResult]{failures}
-  A list containing 2-tuples of \class{TestCase} instances and
-  formatted tracebacks. Each tuple represents a test where a failure
+  A list containing 2-tuples of \class{TestCase} instances and strings
+  holding formatted tracebacks. Each tuple represents a test where a failure
   was explicitly signalled using the \method{TestCase.fail*()} or
   \method{TestCase.assert*()} methods.
   \versionchanged[Contains formatted tracebacks instead of
@@ -817,17 +839,25 @@
 
 \begin{methoddesc}[TestResult]{startTest}{test}
   Called when the test case \var{test} is about to be run.
+  
+  The default implementation simply increments the instance's
+  \code{testsRun} counter.
 \end{methoddesc}
 
 \begin{methoddesc}[TestResult]{stopTest}{test}
-  Called when the test case \var{test} has been executed, regardless
+  Called after the test case \var{test} has been executed, regardless
   of the outcome.
+  
+  The default implementation does nothing.
 \end{methoddesc}
 
 \begin{methoddesc}[TestResult]{addError}{test, err}
   Called when the test case \var{test} raises an unexpected exception
   \var{err} is a tuple of the form returned by \function{sys.exc_info()}:
   \code{(\var{type}, \var{value}, \var{traceback})}.
+  
+  The default implementation appends \code{(\var{test}, \var{err})} to
+  the instance's \code{errors} attribute.
 \end{methoddesc}
 
 \begin{methoddesc}[TestResult]{addFailure}{test, err}
@@ -835,10 +865,15 @@
   \var{err} is a tuple of the form returned by
   \function{sys.exc_info()}:  \code{(\var{type}, \var{value},
   \var{traceback})}.
+  
+  The default implementation appends \code{(\var{test}, \var{err})} to
+  the instance's \code{failures} attribute.
 \end{methoddesc}
 
 \begin{methoddesc}[TestResult]{addSuccess}{test}
   Called when the test case \var{test} succeeds.
+  
+  The default implementation does nothing.
 \end{methoddesc}
 
 
@@ -878,9 +913,12 @@
   Return a suite of all tests cases given a string specifier.
 
   The specifier \var{name} is a ``dotted name'' that may resolve
-  either to a module, a test case class, a \class{TestSuite} instance,
-  a test method within a test case class, or a callable object which
-  returns a \class{TestCase} or \class{TestSuite} instance.
+  either to a module, a test case class, a test method within a test
+  case class, a \class{TestSuite} instance, or a callable object which
+  returns a \class{TestCase} or \class{TestSuite} instance.  These checks
+  are applied in the order listed here; that is, a method on a possible
+  test case class will be picked up as ``a test method within a test
+  case class'', rather than ``a callable object''.
 
   For example, if you have a module \module{SampleTests} containing a
   \class{TestCase}-derived class \class{SampleTestCase} with three test
@@ -905,7 +943,7 @@
 
 \begin{methoddesc}[TestLoader]{getTestCaseNames}{testCaseClass}
   Return a sorted sequence of method names found within
-  \var{testCaseClass}.
+  \var{testCaseClass}; this should be a subclass of \class{TestCase}.
 \end{methoddesc}