[Numpy-discussion] Why are ufunc docstrings useless?

[Robert Kern]

On Thu, May 8, 2008 at 10:39 PM, Anne Archibald
<peridot.faceted at gmail.com> wrote:
> 2008/5/8 Robert Kern <robert.kern at gmail.com>:
>> On Thu, May 8, 2008 at 9:52 PM, Anne Archibald
>> <peridot.faceted at gmail.com> wrote:
>>
>>> Thanks! Done add, reduce, outer, and reduceat. What about __call__?
>>
>> If anyone knows enough to explicitly request a docstring from
>> __call__, they already know what it does.
>
> How exactly are they to find out? It does take additional arguments,
> for example dtype and out - I think.

That should be recorded in the ufunc's main docstring, e.g.
numpy.add.__doc__, since that is what people will actually be calling.
No one will explicitly call numpy.add.__call__(x,y).

> Also, help(np.add) displays the the object, its docstring, its
> methods, and all their docstrings. So it provides a way to get a
> docstring out of __call__ without having to know what it is.

Meh. All it can usefully say is "Refer to the main docstring." Which
is more or less what it currently says.

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