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

[Robert Kern]

On Mon, Jun 23, 2008 at 16:51, Michael McNeil Forbes
<mforbes at physics.ubc.ca> wrote:
>> On Mon, Jun 23, 2008 at 4:51 PM, Robert Kern
>> <robert.kern at gmail.com> wrote:
>>>>>>> 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.
>
> Well perhaps... but do you think that
>
> rand(d0, d1, ..., dn) -> random values
>
> is more exampley than
>
>  >>> r = np.random.rand(3,2,4)
>  >>> r.shape
> (3,2,4)
>
> ?

No. It wasn't an example. It was a specification of the call signature
because it is in an extension module, so the call signature is not
available like it is for pure Python functions. Thus, it needs to be
given in the docstring.

-- 
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