Removed lots of stuff from the module docstring. My intent for 2.4 is

to put details in the LaTeX docs instead, and lots of stuff in the
module docstring wasn't useful anyway.

1 files changed, 18 insertions, 137 deletions

diff --git a/Lib/doctest.py b/Lib/doctest.py
index 56bf551..21cbc32 100644
--- a/Lib/doctest.py
+++ b/Lib/doctest.py
@@ -6,16 +6,15 @@
 
 # Provided as-is; use at your own risk; no warranty; no promises; enjoy!
 
-# [XX] This docstring is out-of-date:
 r"""Module doctest -- a framework for running examples in docstrings.
 
 NORMAL USAGE
 
-In normal use, end each module M with:
+In simplest use, end each module M to be tested with:
 
 def _test():
-    import doctest, M           # replace M with your module's name
-    return doctest.testmod(M)   # ditto
+    import doctest
+    return doctest.testmod()
 
 if __name__ == "__main__":
     _test()
@@ -37,14 +36,20 @@ python M.py -v
 and a detailed report of all examples tried is printed to stdout, along
 with assorted summaries at the end.
 
-You can force verbose mode by passing "verbose=1" to testmod, or prohibit
-it by passing "verbose=0".  In either of those cases, sys.argv is not
+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?
 
@@ -59,27 +64,13 @@ WHICH DOCSTRINGS ARE EXAMINED?
 + 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 even if the name is private, and strings are searched
-  directly as if they were docstrings.  In output, a key K in M.__test__
-  appears with name
+  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.  All names reached from
-M.__test__ are searched.
-
-Optionally, functions with private names can be skipped (unless listed in
-M.__test__) by supplying a function to the "isprivate" argument that will
-identify private functions.  For convenience, one such function is
-supplied.  docttest.is_private considers a name to be private if it begins
-with an underscore (like "_my_func") but doesn't both begin and end with
-(at least) two underscores (like "__init__").  By supplying this function
-or your own "isprivate" function to testmod, the behavior can be customized.
-
-If you want to test docstrings in objects with private names too, stuff
-them into an M.__test__ dict, or see ADVANCED USAGE below (e.g., pass your
-own isprivate function to Tester's constructor, or call the rundoc method
-of a Tester instance).
+their contained methods and nested classes.
+
 
 WHAT'S THE EXECUTION CONTEXT?
 
@@ -96,48 +87,6 @@ You can force use of your own dict as the execution context by passing
 M.__dict__ merged with the globals from other imported modules.
 
 
-WHAT IF I WANT TO TEST A WHOLE PACKAGE?
-
-Piece o' cake, provided the modules do their testing from docstrings.
-Here's the test.py I use for the world's most elaborate Rational/
-floating-base-conversion pkg (which I'll distribute some day):
-
-from Rational import Cvt
-from Rational import Format
-from Rational import machprec
-from Rational import Rat
-from Rational import Round
-from Rational import utils
-
-modules = (Cvt,
-           Format,
-           machprec,
-           Rat,
-           Round,
-           utils)
-
-def _test():
-    import doctest
-    import sys
-    verbose = "-v" in sys.argv
-    for mod in modules:
-        doctest.testmod(mod, verbose=verbose, report=0)
-    doctest.master.summarize()
-
-if __name__ == "__main__":
-    _test()
-
-IOW, it just runs testmod on all the pkg modules.  testmod remembers the
-names and outcomes (# of failures, # of tries) for each item it's seen, and
-passing "report=0" prevents it from printing a summary in verbose mode.
-Instead, the summary is delayed until all modules have been tested, and
-then "doctest.master.summarize()" forces the summary at the end.
-
-So this is very nice in practice:  each module can be tested individually
-with almost no work beyond writing up docstring examples, and collections
-of modules can be tested too as a unit with no more work than the above.
-
-
 WHAT ABOUT EXCEPTIONS?
 
 No problem, as long as the only output generated by the example is the
@@ -149,25 +98,10 @@ traceback itself.  For example:
     ValueError: list.remove(x): x not in list
     >>>
 
-Note that only the exception type and value are compared (specifically,
-only the last line in the traceback).
-
+Note that only the exception type and value are compared.
 
-ADVANCED USAGE
 
-doctest.testmod() captures the testing policy I find most useful most
-often.  You may want other policies.
-
-testmod() actually creates a local instance of class doctest.Tester, runs
-appropriate methods of that class, and merges the results into global
-Tester instance doctest.master.
-
-You can create your own instances of doctest.Tester, and so build your own
-policies, or even run methods of doctest.master directly.  See
-doctest.Tester.__doc__ for details.
-
-
-SO WHAT DOES A DOCSTRING EXAMPLE LOOK LIKE ALREADY!?
+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
@@ -197,9 +131,6 @@ containing the code, and the expected output (if any) extends to the next
 
 Bummers:
 
-+ Expected output cannot contain an all-whitespace line, since such a line
-  is taken to signal the end of expected output.
-
 + Output to stdout is captured, but not output to stderr (exception
   tracebacks are captured via a different means).
 
@@ -234,57 +165,7 @@ 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, leading to this output in verbose mode:
-
-Running doctest.__doc__
-Trying: [1, 2, 3].remove(42)
-Expecting:
-Traceback (most recent call last):
-  File "<stdin>", line 1, in ?
-ValueError: list.remove(x): x not in list
-ok
-Trying: x = 12
-Expecting: nothing
-ok
-Trying: x
-Expecting: 12
-ok
-Trying:
-if x == 13:
-    print "yes"
-else:
-    print "no"
-    print "NO"
-    print "NO!!!"
-Expecting:
-no
-NO
-NO!!!
-ok
-... and a bunch more like that, with this summary at the end:
-
-5 items had no tests:
-    doctest.Tester.__init__
-    doctest.Tester.run__test__
-    doctest.Tester.summarize
-    doctest.run_docstring_examples
-    doctest.testmod
-12 items passed all tests:
-   8 tests in doctest
-   6 tests in doctest.Tester
-  10 tests in doctest.Tester.merge
-  14 tests in doctest.Tester.rundict
-   3 tests in doctest.Tester.rundoc
-   3 tests in doctest.Tester.runstring
-   2 tests in doctest.__test__._TestClass
-   2 tests in doctest.__test__._TestClass.__init__
-   2 tests in doctest.__test__._TestClass.get
-   1 tests in doctest.__test__._TestClass.square
-   2 tests in doctest.__test__.string
-   7 tests in doctest.is_private
-60 tests in 17 items.
-60 passed and 0 failed.
-Test passed.
+executed.
 """
 
 __all__ = [