On Dec 29, 2007 6:51 PM, Charles R Harris charlesr.harris@gmail.com wrote:

If not, we should definitely decide on the structure of the docstrings and stick to it.

+100

I'm about to commit docstrings for scimath (what I started yesterday). After some fixes to the numpy build, I can now work in-place and get things like

tlon[~]> nosetests --with-doctest numpy.lib.scimath ....... ---------------------------------------------------------------------- Ran 7 tests in 0.660s

OK

Which is nice. For now I'm adhering to what was in the guide:

log?

Type: function Base Class: <type 'function'> Namespace: Interactive File: /home/installers/src/scipy/numpy/numpy/lib/scimath.py Definition: log(x) Docstring: Return the natural logarithm of x.

If x contains negative inputs, the answer is computed and returned in the complex domain.

Parameters ---------- x : array_like

Returns ------- array_like

Examples -------- >>> import math

>>> log(math.exp(1)) 1.0

Negative arguments are correctly handled (recall that for negative arguments, the identity exp(log(z))==z does not hold anymore):

>>> log(-math.exp(1)) == (1+1j*math.pi) True

But it's easy enough to fix them if a change is made. But let's settle this *soon* please, so that if changes need to be made it's just a few, and we can just move on.

At this point we just need *a* decision. It doesn't need to be perfect, but any docstring is better than our canonical:

np.cumsum?

Type: function Base Class: <type 'function'> Namespace: Interactive File: /home/fperez/usr/opt/lib/python2.5/site-packages/numpy/core/fromnumeric.py Definition: np.cumsum(a, axis=None, dtype=None, out=None) Docstring: Sum the array over the given axis.

Blah, Blah.

I got that 'Blah blah' while lecturing to 20 developers and scientists at a workshop at NCAR (the National Center for Atmospheric Research in Boulder), projected on a 20 foot-wide screen. A bit embarrassing, I must admit.

So please, no more code without full docstrings in numpy/scipy....

Cheers,

f