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

[David Goldsmith]

On Tue, Jun 1, 2010 at 10:41 PM, Scott Sinclair <scott.sinclair.za at 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?
> >
> > 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."
:-)

 DG

> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>



-- 
Mathematician: noun, someone who disavows certainty when their uncertainty
set is non-empty, even if that set has measure zero.

Hope: noun, that delusive spirit which escaped Pandora's jar and, with her
lies, prevents mankind from committing a general suicide.  (As interpreted
by Robert Graves)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20100601/4f85b46f/attachment.html>