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

Benjamin Root ben.root@ou....
Wed Jun 2 22:28:40 CDT 2010


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@gmail.com>wrote:

> On Wed, Jun 2, 2010 at 7:22 PM, Vincent Davis <vincent@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@scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/scipy-dev/attachments/20100602/0cb3b91a/attachment-0001.html 


More information about the SciPy-Dev mailing list