[SciPy-user] Docstring standards for NumPy and SciPy
perry at stsci.edu
Fri Jan 12 10:44:38 CST 2007
A few more comments on this topic.
1) regarding having ipython process the docstring. I suppose that one
could argue that preprocessing the docstring universally may screw up
those not written for the markup language. Wouldn't it be possible to
put some sort of marker in the module (flag definition, e.g.,
ipdoc=True) so that ipython could check the module that the docstring
comes from to see if it should be preprocessed? Maybe this isn't
worth worrying about.
2) I personally much prefer "arguments" to "inputs" (and secondarily
"parameters" to "inputs"). Some functions may modify their arguments.
Some arguments may be both inputs and outputs. The explanation should
indicate which arguments may be modified by the function (I'd prefer
some very terse notation that was standard to scipy/numpy, e.g.,
"arr: [m] the 2-d array to be FFT'ed. This is done in-place." Yes,
this example is redundant, but is is nice to make it very clear
visually that the argument is modified in some way without having to
read the whole thing).
3) I like the idea of some loose indication of the type. But here
also it would be nice for some terse (for common cases) notation
*and* some precision on terminology. For example, in Fernando's
example, does number mean complex number? I'd tend to think that in
most common cases, a numerical type includes all those lower types.
If I require some sort of float, an int will suffice unless
explicitly listed as not. So perhaps the use of b, i, f, c for
boolean, int, float, or complex interpretation of the parameter with
the default interpretation including any lower type. Perhaps some
notation for dimensionality should be standardized (e.g., 2d, <3d,
nd, s) where s means scalar only (mind you, I haven't given the
notation much thought so I'm not wedded to these examples). The use
of a concise standard notation may be a little bit of an impediment
to new users, but if learning it is easy and they key is easy to get,
it can make the documentation both easier to scan and much less
wordy, and more precise.
4) I also tend to think there is sometimes some imprecision regarding
what are keyword parameters. If I'm not mistaken, rarely used
positional parameters that have defaults are often referred to as
keyword arguments (since that is often how they are specified, i.e.,
using keyword syntax). So, in the case of these docstrings, are
these to go under arguments or keywords?
5) along this line, it would be nice to have a standard notation for
default values for arguments.
Perhaps this all getting into premature detail, but I don't see why
this can't all be settled ahead of time (and save some grief down the
More information about the SciPy-user