[Numpy-discussion] Why are ufunc docstrings useless?

[Robert Kern]

On Thu, May 8, 2008 at 11:31 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 10:39 PM, Anne Archibald
>> <peridot.faceted at gmail.com> wrote:
>>> 2008/5/8 Robert Kern <robert.kern at gmail.com>:
>>>>
>>>> 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.
>
> So is the custom that double-underscore methods get documented in the
> class docstring and normal methods get documented in their own
> docstrings?

No. Objects whose main purpose is to be callable should document their
call signature in the main docstring since that's where the objects
they are mimiccing (functions) have their docstring.

In this case, there is also a technical reason: you can't override
add.__call__.__doc__, just ufunc.__call__.__doc__, but the call
signatures vary between ufuncs.

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