[SciPy-user] Docstring standards for NumPy and SciPy

[Robert Kern]

Perry Greenfield wrote:

> 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.

I'd rather use the full words.

> 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.

I've taken to using shape tuples: (n, m), (n,), etc. For several arguments that
may need to have some axes of the same size, this is a quite terse way of
expressing that. It also gives you a way to refer to a specific axis ("the n
vectors of m dimensions each").

> 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?

I would suggest that there are no "positional arguments with defaults." They are
all keyword arguments. pylab-style argument lists should be forbidden in numpy
and scipy.  :-)

So I'd go with Arguments: for everything you have to specify and Additional
Arguments: for everything that you don't.

> 5) along this line, it would be nice to have a standard notation for  
> default values for arguments.

Actually, I'd suggest leaving them out of the docstring entirely. The
introspection tells you what the default is. If there is some special processing
of that default value ("if arg is None: arg = something_else()"), it should be
explained in prose (mostly because the general case needs explanation in prose
and can't be reduced to "default=something").

-- 
Robert Kern

"I have come to believe that the whole world is an enigma, a harmless enigma
 that is made terrible by our own mad attempt to interpret it as though it had
 an underlying truth."
  -- Umberto Eco