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

[Ralf Gommers]

On Wed, Jun 16, 2010 at 10:55 AM, David Goldsmith
<d.l.goldsmith at gmail.com>wrote:

>
> Well, the deadline is upon us; here's my concrete proposal:
>
> http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines#docstring-standardshould 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*...
>

The short summary gets pulled into function overview tables, it should
really be the first line of the docstring. Please put the deprecation
warning just after it.

Content looks fine to me.


>
> To submit this as a patch, do I grab HOWTO_DOCUMENT.txt, modify it,


Yes so far.


> then attach the modified version as an attachment to the ticket?
>
> Make that a diff please.

Cheers,
Ralf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20100616/48e123cb/attachment.html>