[Numpy-discussion] Code samples in docstrings mistaken as doctests
Mon Jun 23 15:51:20 CDT 2008
On Mon, Jun 23, 2008 at 15:44, Michael McNeil Forbes
> On 23 Jun 2008, at 1:28 PM, Anne Archibald wrote:
>> 2008/6/23 Michael McNeil Forbes <firstname.lastname@example.org>:
>>> 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 agree that this can be awkward sometimes, and should certainly not
> be policy, but one can usually get around this. Instead of printing
> the result, you can use it, or demonstrate porperties:
> >>> random_array = np.random.rand(3,4)
> >>> random_array.shape
> >>> random_array.max() < 1
> >>> random_array.min() > 0
Yes, this makes it doctestable, but you've destroyed the exampleness.
It should be policy *not* to do this.
"I have come to believe that the whole world is an enigma, a harmless
enigma that is made terrible by our own mad attempt to interpret it as
though it had an underlying truth."
-- Umberto Eco
More information about the Numpy-discussion