[SciPy-Dev] Clarification: is the Extended Summary section optional?

[Ralf Gommers]

On Wed, Jun 2, 2010 at 2:44 PM, David Goldsmith <d.l.goldsmith at gmail.com>wrote:

> On Tue, Jun 1, 2010 at 10:41 PM, Scott Sinclair <scott.sinclair.za@
> gmail.com> wrote:
>
>> On 1 June 2010 22:48, David Goldsmith <d.l.goldsmith at gmail.com> wrote:
>> > 2010/6/1 Stéfan van der Walt <stefan at sun.ac.za>
>> >>
>> >> On 1 June 2010 13:32, David Goldsmith <d.l.goldsmith at gmail.com> wrote:
>> >> > The docstring Standard seems to be careful to note which sections are
>> >> > considered optional, and the "Extended Summary" is *not* on that
>> list.
>> >> > However, I'm encountering many SciPy docstrings in the Wiki lacking
>> this
>> >> > section and yet marked as "Needs review": should I ignore this
>> >> > deficiency
>> >> > and add a ticket to clarify the Standard, or should such docstrings
>> be
>> >> > moved
>> >> > back to "Being written"?
>> >>
>> >> Typically, there is no reason not to have an extended section.  Can
>> >> you give an example where it would seem unnecessary?
>>
>
I think we shouldn't go overboard here. In the great majority of cases it's
needed but sometimes there's just not much info to add besides what's in the
summary and parameter description. Examples:
http://docs.scipy.org/numpy/docs/numpy.core.umath.add/
http://docs.scipy.org/numpy/docs/numpy.lib.ufunclike.isneginf/
http://docs.scipy.org/numpy/docs/numpy.core.umath.logical_or/

These are all good docstrings and should not be reset to "needs editing"
imho. And if you really have info to add, I suggest to just add it the
moment you see it - will be a lot more productive in the end.

Finally, there's a huge amount of low hanging fruit in the scipy docs. Why
not just take a module and dig in? These details can wait for a while.

Best regards,
Ralf


>
>> > No: my position would appear to be the same as yours, and my inclination
>> > would be to "revert" them to "Being written."
>>
>> Wouldn't it better to revert them to "Needs editing" instead? The
>> "Being written" status implies that someone is actively working on the
>> docstring...
>>
>> Cheers,
>> Scott
>>
>
> Correct; actually, what I'm doing for these, and other prematurely promoted
> docstrings, is checking the log: only if the most recent edit was
> substantial and within the last 6 mo. (indicating some amount of recent
> "ownership") am I pushing back to "Being written," otherwise, which, so far,
> is the dominant case by far, I am indeed pushing it back to "Needs editing."
> :-)
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20100602/036001b0/attachment.html>