[SciPy-dev] module docstrings

[David Goldsmith]

"Works for me." :-)  Are there *any* that presently conform to that
standard?  (Or do they consequently all need editing?)

DG

On Sun, Oct 25, 2009 at 4: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
>
> 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
>
>
> _______________________________________________
> Scipy-dev mailing list
> Scipy-dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20091025/3cc90e5d/attachment.html>