[Python-Dev] PEP 318: Let's propose some useful built-in decorators

[Tim Peters]

[Guido]
> ...
> doctest_script(multi_line_string) -- specifies a doctest script, for
> use by the doctest module (if this is absent, it will continue to look
> in the doc string).  I like to separate the doctest script from the
> actual documentation string because, when used for rigorous unit
> testing (as in Jim&Tim's talk at PyCON), the doctest script is too
> long to double as reasonable documentation.  Maybe this should be
> imported from the doctest module.

Let me try to squash this one before it gains traction from people who don't
use doctest anyway <wink>.  Burying a large triple-quoted string inside a
function call inside an indented "list" isn't going to help the readability
of anything.  Zope use is moving toward putting large doctests into their
own .py file, or, more recently, into their own .txt file.  An example of
the former:

    http://cvs.zope.org/ZODB/src/ZODB/tests/testmvcc.py

The idea that "too long" makes for unreasonable documentation doesn't make
sense to me:  these long doctests read like tutorials liberally sprinkled
with Python examples, and are the best docs some of these subsystems will
ever have.  Indeed, the Python Tutorial is a prime example of something that
"should be" a doctest, and I think that's exceptionally good documentation.

Of course this doesn't preclude putting a judiciously few examples in
docstrings either (also for doctest chewing), but I'd rather encourage
people who want more than that to go all the way, and write a tutorial-style
large doctest in its own file.