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

[Anne Archibald]

2008/6/23 Alan McIntyre <alan.mcintyre at gmail.com>:
> On Mon, Jun 23, 2008 at 3:21 PM, Stéfan van der Walt <stefan at sun.ac.za> wrote:
>> Another alternative is to replace +SKIP with something like +IGNORE.
>> That way, the statement is still executed, we just don't care about
>> its outcome.  If we skip the line entirely, it often affects the rest
>> of the tests later on.
>
> 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.  If the
> code that's currently in docstrings needs to be retained as test code,
> I'll gladly take the time to put it into a test_ module where it
> doesn't get in the way of documentation.  I'll defer to the consensus,
> though.

I think doctests are valuable: it's very hard for the documentation to
get out of sync with the code, and it makes it very easy to write
tests, particularly in light of the wiki documentation framework. But
I think encrusting examples with weird comments will be a pain for
documentors and off-putting to users. Perhaps doctests can be
positively marked, in some relatively unobtrusive way?

Anne