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

[Alan McIntyre]

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.