[SciPy-Dev] Warning of deprecation in doc's ?

[David Goldsmith]

On Tue, Jun 15, 2010 at 8:02 PM, Vincent Davis <vincent at vincentdavis.net>wrote:

> On Tue, Jun 15, 2010 at 8:55 PM, David Goldsmith
> <d.l.goldsmith at gmail.com> wrote:
> > On Thu, Jun 3, 2010 at 11:18 AM, David Goldsmith <
> d.l.goldsmith at gmail.com>
> > wrote:
> >>
> >> http://projects.scipy.org/numpy/ticket/1501
> >>
> >> Filed Description:
> >>
> >> "Presently, the docstring standard does not specify how to note that an
> >> object is to be deprecated; it has been proposed that this needs to be
> >> rectified.
> >>
> >> "Obviously, this should be an optional section in general, but required
> >> for objects once it is decided that they are to be deprecated.
> >>
> >> "Discussion on scipy-dev agreed that this section should be at or near
> the
> >> top, but at the top or between the One-line and Extended Summaries have
> both
> >> been proposed - we will try to reach a consensus [in the ticket
> comments].
> >>
> >> "Proposed format is to utilize Sphinx' .. deprecated:: directive;
> someone
> >> please provide a concrete example of what this looks like (for example,
> does
> >> this directive support multi-line content, and if so, what does that
> look
> >> like).
> >>
> >> "Proposed content: summaries of deprecation schedule (in version number
> >> time, not real time) and justification for deprecation (e.g., being
> >> replaced, duplicates extant functionality elsewhere); existing
> alternatives
> >> to obtain the same functionality. (Feel strongly that it should contain
> >> something else? Add it below as a comment.)
> >>
> >> "IMO, we should try to decide on this and update the standard by June 15
> >> at the latest.
> >>
> >> "Have I forgotten anything"
> >>
> >> DG
> >
> > Well, the deadline is upon us; here's my concrete proposal:
> >
> http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines#docstring-standard
> > should be modified as follows:
> >
> > Present Content
> >      :
> > Sections
> >
> > The sections of the docstring are:
> >
> > 1.  Short summary...
> >
> > Proposed Content
> >      :
> > Sections
> >
> > The sections of the docstring are:
> >
> > 0.  Deprecation warning (optional, but required if the object is
> designated
> > for deprecation)
> >
> >      .. deprecated:: <deprecation schedule>, <justification, if known>
> > (optional), <functional equivalents, if extant> (optional), <example>
> >
> > 1.  Sort summary...
> >
> > To submit this as a patch, do I grab HOWTO_DOCUMENT.txt, modify it, then
> > attach the modified version as an attachment to the ticket?
> >
>
> You must have had that on your calendar. It looks good to me.
>

Nope. I should have, but actually, editing some 'really bad docstrings'
(TM), I discovered a set that raise NotImplementedError and that got me
thinking about where I should place a warning to that effect, which in turn
jogged my memory about the deprecation section deadline. :-)

DG


> Vincent
>
>
> > DG
> >
> >
> >
> > _______________________________________________
> > 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
>



-- 
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/20100615/5b7db124/attachment.html>