[Numpy-discussion] Doctests vs. unittests

[Sasha]

In a recent thread (see "Test fails for rev. 2473") Albert suggested
that unittests should be preferred  over doctests.  I disagree and
would like to hear some opinions on this topic.

I believe unitests and doctests serve two distinct purposes. 
Unittests should provide bigger coverage than doctests, particularly
tests for rarely used corner cases or tests that are added when a bug
is fixed should be written as unittests.   Doctests should mostly be
used as automatically tested examples in docstrings.  Doctests should
be selected primarily based on their readibility and relevance to the
rest of the docstring rather than completeness of test coverage.

There is one use of doctests that may justify conversion to unittests.
 We should encourage users to submit tests and doctest format is much
more accessible than unittest.  Doctests that appear in separate test
files rather than as examples in docstings should probably be
converted eventually, but this should not discourage anyone from
writing the tests as doctests in the first place.