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