[Numpy-discussion] umath ufunc docstrings

[Pauli Virtanen]

la, 2008-05-31 kello 15:02 -0500, Travis E. Oliphant kirjoitti:
> 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.

The problem here was simply that inserting multi-line docstring into the
UFunc list in generate_umath.py would make the list unwieldy to edit.

Moreover, while this would probably still be possible to automate
reliably, it is easier if there is only one way that we define
docstrings for C objects. I already wrote code for the add_newdoc
syntax, so it seemed cleanest to re-use it.

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

This was for making the docstrings of the same form as those in
add_newdocs.py; there the signature must always be contained in the
docstring. I thought that the automatic signature was such a small gain
that uniformity overruled it here. If you think otherwise, I'll just
special-case the handling of ufunc docstrings in the documentation
tools, which is not a big deal.

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

Has a bug report for pydoc already been filled so that it might have a
change of hitting 3.0?

	Pauli