[Numpy-discussion] Doc strings for ufuncs

[Charles G Waldman]

I really, really, really like the Cephes module and a lot of the work
Travis Oliphant has been doing on Numeric Python.  Nice to see Numeric
getting more and more powerful all the time.

However, as more and more functions get added to the libraries, their
names become more and more obscure, and it sure would be nice to have
doc-strings for them.  For the stock Numeric ufuncs like "add", the
meanings are self-evident, but things like "pdtri" and "incbet" are a
bit less obvious.

(One of my pet peeves with Python is that there are so many functions
and classes with empty doc-strings.  Bit by bit, I'm trying to add
them in).


However, one little problem with the current Numeric implementation is
that ufunc objects don't have support for a doc string, the doc string
is hardwired in the type object, and comes up as:


"Optimizied FUNCtions make it possible to implement arithmetic with
matrices efficiently"

This is not only non-helpful, it's misspelled ("Optimizied"?)

Well, according to the charter,  a well-behaved Nummie will
      
      "Fix bugs at will, without prior consultation."

But a well-behaved Nummie wil also 

       "Add new features only after consultation with other Nummies"

So, I hereby declare doing something about the useless doc-strings to
be fixing a bug and not adding a feature ;-)


The patch below adds doc strings to all the ufuncs in the Cephes
module.  They are automatically extracted from the HTML documentation
for the Cephes module.  (In the process of doing this, I also added
some missing items to said HTML documentation).

This patch depends on another patch, which I am submitting via the
SourceForge, which allows ufunc objects to have doc strings.

With these patches, you get this:

>>> import cephes
>>> print cephes.incbet.__doc__
incbet(a,b,x) returns the incomplete beta integral of the
arguments, evaluated from zero to x: gamma(a+b) / (gamma(a)*gamma(b))
* integral(t**(a-1) (1-t)**(b-1), t=0..x).

instead of this:

>>> print cephes.incbet.__doc__
Optimizied FUNCtions make it possible to implement arithmetic with
matrices efficiently

Isn't that nicer?

"Ni-Ni-Numpy!"

Here's the "gendoc.py" script to pull the docstrings out of
included_functions.h:

-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: gendoc.py
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20000323/62cf6c72/attachment.ksh>
-------------- next part --------------

And here are the patches to cephes:

-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: cephes-patch
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20000323/62cf6c72/attachment-0001.ksh>
-------------- next part --------------

NB:  This stuff won't work at all without the corresponding patches to
the Numeric core, to be posted shortly to the sourceforge site.