[SciPy-dev] module docstrings
Sun Oct 25 06:58:48 CDT 2009
The doc standard does not say anything about module docstrings, and before
starting to clean those up it would be nice to agree on a format.
Right now there are modules that:
- do not have any docstring (matrixlib, fromnumeric, ..)
- have license/author info in the docstring (scipy.interpolate.fitpack, ..)
- list their routines (linalg, core, lib, ..)
* some of these have a routines rst doc: routines.linalg.rst exists,
routines.lib.rst does not.
- have a single summary line (distutils, ..)
- have some basic explanation (ma, scimath, ..)
What do you all think about the following? :
1. every module needs a docstring with at least a summary line.
2. follow the doc standard where relevant, so typically:
- summary line
- extended summary paragraph(s)
- see also, if needed
- notes, if needed
- references, if needed
3. no routine listing in the docstring, each module gets a corresponding
4. license and author info can be in the source file, but not in the
docstring. (same principle for author info in reST docs by the way).
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Scipy-dev