[SciPy-user] Docstring standards for NumPy and SciPy
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.
>:return: named, list, of, outputs
> - named: explanation
> - list: more detail
> - of: blah, blah.
> - outputs: even more blah
> A little-used input not always needed.
> 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
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
More information about the SciPy-user