[SciPy-dev] module docstrings

Ralf Gommers ralf.gommers@googlemail....
Sun Oct 25 12:32:16 CDT 2009


On Sun, Oct 25, 2009 at 6:14 PM, David Goldsmith <d.l.goldsmith@gmail.com>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.

Ralf


>
> DG
>
> On Sun, Oct 25, 2009 at 4:58 AM, Ralf Gommers <ralf.gommers@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@scipy.org
>> http://mail.scipy.org/mailman/listinfo/scipy-dev
>>
>>
>
> _______________________________________________
> Scipy-dev mailing list
> Scipy-dev@scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/scipy-dev/attachments/20091025/4b81cc0c/attachment.html 


More information about the Scipy-dev mailing list