At 01:40 AM 6/29/2007 -0400, Chris McDonough wrote:
>When coverage gets good, "documentation-ness" of tests suffers.
The question is more one of, "documentation for whom?". You can
write separate documents for library users than for library
extenders/developers. I don't put doctests in docstrings, but if I
did, I'd probably only put user doctests there. As it is, I normally
split my doctests into multiple files for different audiences, or
under different headings in one large file.
For example, if you look at the BytecodeAssembler documentation:
http://peak.telecommunity.com/DevCenter/BytecodeAssembler
You'll see that the assertion and invariant testing is mostly
relegated to a separate section.
Another library I'm working on has two doctest files for users (a
quick intro and a developer guide/reference) and a separate file that
tests all the innards. So, there are a lot of ways to use doctests
effectively, at least if you're doing them in text files, rather than
in your docstrings. I've actually never put a doctest in a
docstring; it always seems like overkill to me. (Especially since
reST doctests can be made into nice HTML pages like the above!)
_______________________________________________
Python-3000 mailing list
Python-3000@python.org
http://mail.python.org/mailman/listinfo/python-3000
Unsubscribe:
http://mail.python.org/mailman/options/python-3000/archive%40mail-archive.com
