[Numpy-discussion] Code samples in docstrings mistaken as doctests

[Anne Archibald]

2008/6/23 Michael McNeil Forbes <mforbes at physics.ubc.ca>:
>> On 23 Jun 2008, at 12:37 PM, Alan McIntyre wrote:
>>> Ugh.  That just seems like a lot of unreadable ugliness to me.  If
>>> this comment magic is the only way to make that stuff execute
>>> properly
>>> under doctest, I think I'd rather just skip it in favor of clean,
>>> uncluttered, non-doctestable code samples in the docstrings.
>
> Another perspective: doctests ensure that documentation stays up to
> date (if the behaviour or interface changes, then tests will fail
> indicating that the documentation also needs to be updated.)
>
> Thus, one can argue that all examples should also be doctests.  This
> generally makes things a little more ugly, but much less ambiguous.

This is a bit awkward. How do you give an example for a random-number
generator? Even if you are willing to include a seed in each
statement, misleading users into thinking it's necessary, the value
returned for a given seed is not necessarily part of the interface a
random-number generator agrees to support.

I do agree that as many examples as possible should be doctests, but I
don't think we should restrict the examples we are allowed to give to
only those that can be made to serve as doctests.

Anne