[SciPy-dev] module docstrings
Charles R Harris
Fri Oct 30 20:21:28 CDT 2009
On Sun, Oct 25, 2009 at 5: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
I like routine listings. They may not add much to the processed
documentation, but I find it helpful to have routines listed up top with
some short notes when looking at the source. It is also an easy way to see
what is in a module without having to browse through its directory listing.
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