[SciPy-dev] module docstrings
Sun Oct 25 12:32:16 CDT 2009
On Sun, Oct 25, 2009 at 6:14 PM, David Goldsmith <firstname.lastname@example.org>wrote:
> "Works for me." :-) Are there *any* that presently conform to that
> standard? (Or do they consequently all need editing?)
Pretty much all of them still need editing. The only one I've worked on is
numpy.lib.format, which is maybe too long for a docstring.
numpy.ma and numpy.scimath are pretty good already.
> On Sun, Oct 25, 2009 at 4:58 AM, Ralf Gommers <email@example.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).
>> Scipy-dev mailing list
> Scipy-dev mailing list
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Scipy-dev