[SciPy-user] Docstring standards for NumPy and SciPy

Travis Oliphant oliphant at ee.byu.edu
Wed Jan 10 11:21:56 CST 2007


Alan G Isaac wrote:

>
>"""
>one-line summary not using variable names or the function name
>
>A few sentences giving an extended description.
>
>:Parameters:
>   `var1`
>        Explanation
>   `variable2`
>        Explanation
>:return:  named, list, of, outputs
>   - named:     explanation
>   - list:      more detail
>   - of:        blah, blah.
>   - outputs:   even more blah
>:Keywords:
>   `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.
>:note: Additional notes if needed
>:note: More additional notes if needed
>:author: name (date):  notes about what was done
>:author: name (date):  major documentation updates can be included here also.
>:see: func1 -- any notes about the relationship
>:see: func2 --
>:see: func3 --
>:see: func4, func5, func6
>  
>

Several things:

1)  I don't like ":Input:"  "Input:" looks much better to me.  The extra 
':' is noise for the human reader.

2) I don't like little back-ticks on the variable names, they are just 
line noise.  It is easily inferred that these are parameters.

I prefer the names  "Inputs:" and "Outputs:" because these are already 
pretty standard throughout SciPy. 

Why switch to underlining in Algorithm and Examples and Comments 
Section.   I don't necessarily mind it, but it seems arbitrary.

I'm happy to have a notes section.  I don't care if the author field is 
there or not.   It is nice to use tools like epydoc, but we should not 
force ourselves to use there stuff since we will have to hack it anyway 
to manage math.  Therefor, why not "hack" it to manage the format we 
decide on.


-Travis




More information about the SciPy-user mailing list