Removed most of the module docstring. There's too much to explain now,

and the LaTeX docs are in increasingly good shape.

Lib/doctest.py

@@ -8,13 +8,11 @@
 
 r"""Module doctest -- a framework for running examples in docstrings.
 
-NORMAL USAGE
-
 In simplest use, end each module M to be tested with:
 
 def _test():
     import doctest
-    return doctest.testmod()
+    doctest.testmod()
 
 if __name__ == "__main__":
     _test()
@@ -40,133 +38,13 @@ You can force verbose mode by passing "verbose=True" to testmod, or prohibit
 it by passing "verbose=False".  In either of those cases, sys.argv is not
 examined by testmod.
 
-In any case, testmod returns a 2-tuple of ints (f, t), where f is the
-number of docstring examples that failed and t is the total number of
-docstring examples attempted.
-
 There are a variety of other ways to run doctests, including integration
 with the unittest framework, and support for running non-Python text
 files containing doctests.  There are also many ways to override parts
 of doctest's default behaviors.  See the Library Reference Manual for
 details.
-
-
-WHICH DOCSTRINGS ARE EXAMINED?
-
-+ M.__doc__.
-
-+ f.__doc__ for all functions f in M.__dict__.values(), except those
-  defined in other modules.
-
-+ C.__doc__ for all classes C in M.__dict__.values(), except those
-  defined in other modules.
-
-+ If M.__test__ exists and "is true", it must be a dict, and
-  each entry maps a (string) name to a function object, class object, or
-  string.  Function and class object docstrings found from M.__test__
-  are searched, and strings are searched directly as if they were docstrings.
-  In output, a key K in M.__test__ appears with name
-      <name of M>.__test__.K
-
-Any classes found are recursively searched similarly, to test docstrings in
-their contained methods and nested classes.
-
-
-WHAT'S THE EXECUTION CONTEXT?
-
-By default, each time testmod finds a docstring to test, it uses a *copy*
-of M's globals (so that running tests on a module doesn't change the
-module's real globals, and so that one test in M can't leave behind crumbs
-that accidentally allow another test to work).  This means examples can
-freely use any names defined at top-level in M.  It also means that sloppy
-imports (see above) can cause examples in external docstrings to use
-globals inappropriate for them.
-
-You can force use of your own dict as the execution context by passing
-"globs=your_dict" to testmod instead.  Presumably this would be a copy of
-M.__dict__ merged with the globals from other imported modules.
-
-
-WHAT ABOUT EXCEPTIONS?
-
-No problem, as long as the only output generated by the example is the
-traceback itself.  For example:
-
-    >>> [1, 2, 3].remove(42)
-    Traceback (most recent call last):
-      File "<stdin>", line 1, in ?
-    ValueError: list.remove(x): x not in list
-    >>>
-
-Note that only the exception type and value are compared.
-
-
-SO WHAT DOES A DOCTEST EXAMPLE LOOK LIKE ALREADY!?
-
-Oh ya.  It's easy!  In most cases a copy-and-paste of an interactive
-console session works fine -- just make sure the leading whitespace is
-rigidly consistent (you can mix tabs and spaces if you're too lazy to do it
-right, but doctest is not in the business of guessing what you think a tab
-means).
-
-    >>> # comments are ignored
-    >>> x = 12
-    >>> x
-    12
-    >>> if x == 13:
-    ...     print "yes"
-    ... else:
-    ...     print "no"
-    ...     print "NO"
-    ...     print "NO!!!"
-    ...
-    no
-    NO
-    NO!!!
-    >>>
-
-Any expected output must immediately follow the final ">>>" or "..." line
-containing the code, and the expected output (if any) extends to the next
-">>>" or all-whitespace line.  That's it.
-
-Bummers:
-
-+ Output to stdout is captured, but not output to stderr (exception
-  tracebacks are captured via a different means).
-
-+ If you continue a line via backslashing in an interactive session,
-  or for any other reason use a backslash, you should use a raw
-  docstring, which will preserve your backslahses exactly as you type
-  them:
-
-      >>> def f(x):
-      ...     r'''Backslashes in a raw docstring: m\n'''
-      >>> print f.__doc__
-      Backslashes in a raw docstring: m\n
-
-  Otherwise, the backslash will be interpreted as part of the string.
-  E.g., the "\n" above would be interpreted as a newline character.
-  Alternatively, you can double each backslash in the doctest version
-  (and not use a raw string):
-
-      >>> def f(x):
-      ...     '''Backslashes in a raw docstring: m\\n'''
-      >>> print f.__doc__
-      Backslashes in a raw docstring: m\n
-
-The starting column doesn't matter:
-
->>> assert "Easy!"
-     >>> import math
-            >>> math.floor(1.9)
-            1.0
-
-and as many leading whitespace characters are stripped from the expected
-output as appeared in the initial ">>>" line that triggered it.
-
-If you execute this very file, the examples above will be found and
-executed.
 """
+
 __docformat__ = 'reStructuredText en'
 
 __all__ = [