[SciPy-user] Docstring standards for NumPy and SciPy

Perry Greenfield 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  
road).

Perry



More information about the SciPy-user mailing list