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

[Bruce Southey]

On 06/02/2010 10:28 PM, Benjamin Root wrote:
> As a power user of these tools, I often will encounter these warnings 
> while bulding my code piece-wise, however, I can easily imagine a case 
> where a regular user simply seeing a useful feature and spending time 
> coding around it, only to discover that it will soon be deprecated.  I 
> would certainly be annoyed in such a case.
>
> A quick and easy way to list deprecations would be towards the end of 
> the docstring, but the user might not scroll all the way down past the 
> feature that they found.  So, to raise visibility, such deprecation 
> warnings should be towards the beginning of the docstring.
>
> Just a thought... is it feasible for the doc building system to scan 
> through the function code and spot a deprecation warning and thereby 
> be able to add a list of deprecation warnings to the docstring?  
> Obviously, such warnings would have to follow some standard format, 
> but it would be neat if such things could be automated.
>
> Just my 2 cents,
> Ben Root
>
> On Wed, Jun 2, 2010 at 10:07 PM, David Goldsmith 
> <d.l.goldsmith at gmail.com <mailto:d.l.goldsmith at gmail.com>> wrote:
>
>     On Wed, Jun 2, 2010 at 7:22 PM, Vincent Davis
>     <vincent at vincentdavis.net <mailto:vincent at vincentdavis.net>> wrote:
>
>         For example scipy.stats.stats.cov when you view source has
>         "scipy.stats.cov is deprecated; please update your code to use
>         numpy.cov." Should this be in the docs ? and is there an
>         example of
>         how this should be pointed out.
>         This is something I actually implemented in a program then
>         discovered
>         that is was deprecated. I would have like that to be in the online
>         docs.
>
>         Thanks
>         Vincent
>
>
>     I vaguely recollect this being discussed before, but I can't find
>     anything about it in our docstring Standard, in our Q+A section,
>     nor (easily) at the Python site (generally, when in doubt, we
>     default to Python docstring standards); so, how 'bout it guys and
>     gals: should deprecation be noted in docstrings and if so, where
>     and how?
>
>     DG
>
>
>     _______________________________________________
>     SciPy-Dev mailing list
>     SciPy-Dev at scipy.org <mailto: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
>    
Users should first check that numpy does not have the functionality that 
a user needs. Duplicated functionality between numpy and scipy is or was 
a main reason for depreciation. There are or were cases where numpy is 
different than scipy but I think these are being corrected as when these 
are found.

Many of the warnings predate the numpy and scipy documentation marathon 
efforts and some depreciations may still be in tickets so it is very 
doubtful that an automated system will detect either of these cases 
anyhow. In the doc marathon someone will have to find these cases and 
deal with them appropriately - noting, as the person who created the 
ticket, that some of the scipy.stats should be gone in the tentative 
scipy 0.9 release.

In the future, someone will have to come up with a rule to force 
documentation change when a depreciation event occurs and then enforce 
it. In fact, for numpy (as scipy does not yet have the same policy) the 
desired documentation changes should be added to:
http://projects.scipy.org/numpy/wiki/ApiDeprecation


Bruce
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20100603/914a3340/attachment.html>