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

[Robert Kern]

On Mon, Jun 23, 2008 at 15:44, Michael McNeil Forbes
<mforbes at physics.ubc.ca> wrote:
> On 23 Jun 2008, at 1:28 PM, Anne Archibald wrote:
>
>> 2008/6/23 Michael McNeil Forbes <mforbes at physics.ubc.ca>:
>>> 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
> (3,4)
>  >>> random_array.max() < 1
> True
>  >>> random_array.min() > 0
> True

Yes, this makes it doctestable, but you've destroyed the exampleness.
It should be policy *not* to do this.

-- 
Robert Kern

"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