2008/6/23 Michael McNeil Forbes <[EMAIL PROTECTED]>: >> 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 _______________________________________________ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
