[SciPy-dev] module docstrings

[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).


Cheers,
Ralf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20091025/b834bd1c/attachment.html>