[SciPy-dev] module docstrings

[Charles R Harris]

On Sun, Oct 25, 2009 at 5:58 AM, Ralf Gommers
<ralf.gommers at googlemail.com>wrote:

> 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).
>
>
Chuck
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20091030/e1938176/attachment.html>