[Numpy-discussion] [SciPy-dev] Doc-day
Fernando Perez
fperez.net@gmail....
Sat Dec 29 19:59:27 CST 2007
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
More information about the Numpy-discussion
mailing list