[SciPy-dev] module docstrings
Sun Oct 25 12:14:06 CDT 2009
"Works for me." :-) Are there *any* that presently conform to that
standard? (Or do they consequently all need editing?)
On Sun, Oct 25, 2009 at 4:58 AM, Ralf Gommers
> Hi all,
> 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
> routines.module.rst file
> 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).
> Scipy-dev mailing list
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Scipy-dev