[Numpy-discussion] Code samples in docstrings mistaken as doctests
Mon Jun 23 15:28:37 CDT 2008
2008/6/23 Michael McNeil Forbes <email@example.com>:
>> 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
>>> 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.
More information about the Numpy-discussion