[Python-Dev] Unit testing (again)

[Tim Peters]

[Tim]
> Not to my mind.  doctest is intentionally picky about exact matches,
> for reasons explained earlier.  If the docs for a thing say "integer
> division or modulo by zero" is expected, but running it says something
> else, the docs are wrong and doctest's primary *purpose* is to point
> that out loudly.

[Guido]
> Of course, this is means that *if* you use doctest, all authoritative
> docs should be in the docstring, and not elsewhere.

I don't know why you would reach that conclusion.  My own Python work in
years past had overwhelmingly little to do with anything in the Python
distribution, and I surely did put all my docs in my modules.  It was my
only realistic choice, and doctest grew in part out of that "gotta put
everything in one file, cuz one file is all I got" way of working.  By
allowing to put the docs for a thing right next to the tests for a thing
right next to the code for a thing, doctest changed the *nature* of that
compromise from a burden to a relative joy.

Doesn't mean the docs couldn't or shouldn't be elsewhere, though, unless you
assume that only the "authoritative docs" need to be accurate (I prefer that
all docs tell the truth <wink>).  I know some people have adapted the guts
of doctest to ensuring that their LaTeX and/or HTML Python examples work as
advertised too.  Cool!  The Python Tutorial is eternally out of synch in
little ways with what the matching release actually does.

> Which brings us back to the eternal question of how to indicate
> mark-up in docstrings.

I announced a few years ago I was done waiting for mark-up to reach
consensus, and was going to just go ahead and write useful docstrings
regardless.  Never had cause to regret that -- mark-up is the tail wagging
the dog, and I don't know why people tolerate it (well, yes I do:  "but
there's no mark-up defined!" is an excuse to put off writing decent docs!
but you really don't need six levels of nested lists-- or even one --to get
99% of the info across).

> Is everything connected to everything?

when-it's-convenient-to-believe-it-and-a-few-times-even-when-not-ly
    y'rs  - tim