[SciPy-user] Docstring standards for NumPy and SciPy

Travis Oliphant oliphant at ee.byu.edu
Wed Jan 10 14:15:08 CST 2007


Robert Kern wrote:

>>"""
>>one-line summary not using variable names or the function name
>>
>>A few sentences giving an extended description.
>>
>>Inputs:
>> var1      -- Explanation
>> variable2 -- Explanation
>>
>>Outputs:  named, list, of, outputs
>> named   -- explanation
>> list    -- more detail
>> of      -- blah, blah.
>> outputs -- even more blah
>>    
>>
>
>My objection to this kind of list is that it uses up a lot of valuable
>horizontal space. Additionally, it either entails annoying column alignment *or*
>it looks really ugly with all of the descriptions unaligned. Look at most of the
>docstrings in scipy for examples. This is the Enthought standard:
>
>  
>
I'm not sure I understand what is taking up horizontal space (do you 
mean the required alighment)?

I do like aligned descriptions.

>Parameters
>----------
>var1 : type of var1 (loosely)
>    Description of var1.
>variable2 : type of variable2 (loosely)
>    Description of variable2.
>kwdarg : type of kwdarg, optional
>    Description of kwdarg.
>
>  
>
This is acceptable in my mind, also. Although I probably like '-' 
instead of ':' as a separator, but just because I'm used to it.

>The (loose) type information is quite handy. Sometimes it is quite difficult to
>tell what kind of thing the function needs from the usual description,
>particularly when both scalars or arrays are flying around.
>  
>
Yeah, I could see that.  As you understand but others may not,  we 
shouldn't get overly specific with the "types" though.  We're supposed 
to be doing duck typing wherever possible.

>The problem with both of these forms is that they are difficult to parse into
>correct lists. One issue that should be noted is that sometimes the description
>of a variable is omitted because the description of the function, the variable
>name, and the type information are more than enough context to tell you
>everything you need to know about the parameter. The only description you can
>give is just a repetition of the information that you just gave. Or two
>variables are substantially similar such that you want to describe them together
>only once.
>
>""" Clip the values of an array.
>
>Parameters
>----------
>arr : array
>lower : number
>upper : number
>    The lower and upper bounds to clip the array against.
>"""
>
>This is one reason why I'm beginning to like the ReST form of this; it always
>has a marker to say that this is part of a list.
>  
>

I don't see why indentation doesn't give you that information already.

>""" Clip the values of an array.
>
>:Parameters:
>  - arr : array
>  - lower : number
>  - upper : number
>    The lower and upper bounds to clip the array against.
>"""
>
>I don't think that you can write a tool that takes the ambiguous forms to the
>unambiguous ones.
>
>  
>
I don't know.  If you require indentation for non list entries, then it 
seems un-ambiguous to me.

>>Additional Inputs:    kwdarg1 -- A little-used input not always needed.
>> kwdarg2 -- Some keyword arguments can and should be given in Inputs
>>            Section.  This is just for "little-used" inputs.
>>    
>>
>
>These should be in the Inputs section, not in a separate section.
>  
>
I don't like this as a requirement because occassionally this clutters 
the inputs list with a lot of inputs that are rarely used.  The common 
usage should be listed.  I'd like there to be an option for an 
Additional Inputs section.

See some of the functions in scipy.optimize for examples.


>  
>
>>Algorithm:
>> Notes about the implemenation algorithm (if needed).
>>
>> This can have multiple paragraphs as can all sections.
>>    
>>
>
>  
>
>Meh. This should be in the multi-line description at the top.
>  
>
I don't know.  Not always.  Sometimes sure, but the algorithm can be 
quite complicated to explain and should therefore be here.   Perhaps we 
should use Algorithm Notes for this section so that it is clear that 
simple algorithms should be explained in the multi-line description part.

>  
>
>>Notes:
>> Additional notes if needed
>>    
>>
>
>Also in the multi-line description.
>  
>
>  
>
>>Authors:
>> name (date):  notes about what was done
>> name (date):  major documentation updates can be included here also.
>>    
>>
>
>I agree with Stefan that this shouldn't be in the docstring.
>  
>
Great.  I have no problem with eliminating this section.

>>See also:
>> * func1 -- any notes about the relationship
>> * func2 --
>> * func3 --
>> (or this can be a comma separated list)
>> func1, func2, func3
>>    
>>
>
>This kind of "See also" section is annoying to maintain, and I think that, as we
>have currently been using them, they aren't very useful. The functions in
>scipy.integrate shouldn't point to every other function in scipy.integrate.
>That's pointless and creates a bunch of similar-looking text that gets ignored.
>They should each point to scipy.integrate itself. If they have a much closer
>relationship to another function (trapz() and cumtrapz() for example), then they
>should include that here, but we should show great restraint when doing so. We
>reduce the utility of this section by being indiscriminate.
>  
>
I tend to agree.  I think one rule of thumb which could be applied to 
use see also only if the additional docstring gives more insight into 
what the current function is actually doing.

>>Examples:
>> examples in doctest format
>>
>>Comments:
>> This section should include anything that should not be displayed in a
>>help
>> or other hard-copy output.  Such things as substitution-directed
>>directives
>> should go here.
>>    
>>
>
>This should be in a comment, not a docstring. Most tools won't be aware of this
>special processing that you need to apply.
>
>  
>
I'm fine with that.  Prefer it actually.

-Travis




More information about the SciPy-user mailing list