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