[SciPy-user] Docstring standards for NumPy and SciPy

[Perry Greenfield]

On Jan 12, 2007, at 3:09 PM, Robert Kern wrote:

> 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.
>
That's fine, but there should still be conventions about what words mean
(e.g., number)

>
> 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.  :-)
>
If you mean that if an argument has a default, it should be treated  
as a keywords and advertised as such, that's fine (or are you arguing  
that it would be impermissible to define functions with positional  
arguments with defaults? If so, that would run contrary to lots of  
current usage). Is it an issue of how these are documented or  
implemented? (If a positional argument has a default, you can't keep  
people from using it in a positional way rather than with keyword- 
style usage.)

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

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

True enough (and I wondered about that right after posting since  
having to specify something that is already in the source code is  
bound to cause error when the docstring isn't updated appropriately).  
Still, when showing the formatted docstring,  it may be helpful to  
show the default as derived from introspection through use of some  
software formatting mechanism (this matches a function argument, does  
it have a default? If yes, show it). Certainly there are lots of  
cases where explanatory text is needed (the default of None usually  
doesn't say much by itself since the software  will usually interpret  
that as meaning something in particular. No software formatting  
system is going to be able to figure that out). But for things that  
aren't None (or odd cases) it can be useful to show.

Perry