[Numpy-discussion] umath ufunc docstrings

[Travis E. Oliphant]

Pauli Virtanen wrote:
> Hi,
>
> I'd like to adjust the way numpy.core.umath ufunc docstrings are defined
> to make them more easy to handle in the ongoing documentation marathon:
>   
Thanks for your efforts here.  It would be good to get an idea of what 
problems you are encountering that led you to the proposed solutions.
> - Remove the signature magic in ufunc_get_doc
>   
I don't see why this is needed and seems like un-necessary 
reshuffling.   The current "magic" handles constructing the signature 
for you just like other functions.   I don't see any argument as to why 
we should get rid of this useful construct.

> - Define ufunc docstrings in a separate module
>   instead of in generate_umath.py, in the same format as in 
>   add_newdocs.py
>   
This seems like it might help so that you can insert strings more easily 
from the wiki.
>
> I was also thinking about the problem with pydoc.help and ufuncs: would
> making PyUFuncObject a subclass of PyFunctionObject be a reasonable fix?
>
>   
It's an interesting idea, but making this work would require having 
ufuncobjects start their C-structures with  a binary-equivalent of the 
PyFunction Object which seems un-necessary, wasteful, and confusing 
later.    I would rather try and fix python's help system so that it 
looks for docstrings when they actually exist.


-Travis