[SciPy-dev] module docstrings

[David Goldsmith]

OK, leave some for me. ;-)

DG

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

>
> On Sun, Oct 25, 2009 at 6:14 PM, David Goldsmith <d.l.goldsmith at 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 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
>>>
>>>
>>
>> _______________________________________________
>> Scipy-dev mailing list
>> Scipy-dev at scipy.org
>> http://mail.scipy.org/mailman/listinfo/scipy-dev
>>
>>
>
> _______________________________________________
> 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/15871c7f/attachment.html>