[SciPy-Dev] documenting scipy.special functions

[josef.pktd at gmail.com]

This came up in https://github.com/scipy/scipy/pull/52

Josef:
One more comment about scipy.special docstrings: From what I have seen
they are semiautomatically created. I think eventually we should
switch to docstrings following the numpy standard. There are several
functions where I would have liked to add more information. The
current docstrings of many special functions are awfully uninformative
about details.

Chris:
As for the comments...that's actually not as simple as it sounds. Or
at least it wasn't. I just submitted a pull request to numpy to help
change that. ufuncs are python objects whose docstrings are read-only.
They are set at object creation. The either (1)must be passed in to
the C function creating the ufunc (at which point you have to have the
docs in some C header file or parse them in from a Python header file
with the docs), or (2) you must reset what the ufunc doc pointer
points to at the C level. The add_newdoc method doesn't work on
ufuncs. (And in fact there are a number of calls to add_newdoc in
numpy/add_newdocs.py that don't change the documentation. It isn't
noticed because add_newdoc specifically catches all errors and does
nothing.)
---

Is it possible to improve the docstring for the scipy.special
functions (in the long run)?

I'm just a consumer of scipy.special, but every once in a while I
would like to add some information to special functions.

for some it looks possible to edit (and bring them to numpy standard),
e.g. http://docs.scipy.org/scipy/docs/scipy.special.orthogonal.hermite/#hermite

others, for example
http://docs.scipy.org/scipy/docs/scipy.special._cephes.pdtr/#pdtr ,
cannot be edited, but there is a lot of information hidden in the
fortran files, if one looks for it long enough.

Josef