> No. The docstring remains documentation. But documentation without
> examples generally sucks, due to the limitations of English in being
> precise. A sharp example can be worth 1,000 words. doctest is being used
> as *intended* to the extent that the embedded examples are helpful for
> documentation purposes. doctest then guarantees the examples continue to
> work exactly as advertised over time (and they don't! examples *always* get
> out of date, but without (something like) doctest they never get repaired).
You're lucky that doctest doesn't return dictionaries! For functions
that return dictionaries, it's much more natural *for documentation
purposes* to write
>>> book()
{'Fred': 'mom', 'Ron': 'Snape'}
than the necessary work-around. You may deny that's a problem, but
once we've explained dictionaries to our users, we can expect them to
understand that if they see instead
>>> book()
{'Ron': 'Snape', 'Fred': 'mom'}
they will understand that that's the same thing. Writing it this way
is easier to read than
>>> book() == {'Ron': 'Snape', 'Fred': 'mom'}
1
I always have to look twice when I see something like that.
> As I suggested at the start, read the docstrings for difflib.py: the
> examples are an integral part of the docs, and you shouldn't get any sense
> that they're there "just for testing" (if you do, the examples are poorly
> chosen, or poorly motivated in the surrounding commentary).
They are also more voluminous than I'd like the docs for difflib to be...
--Guido van Rossum (home page: http://www.python.org/~guido/)
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4