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

Benjamin Root ben.root@ou....
Thu Jun 3 09:49:53 CDT 2010


On Thu, Jun 3, 2010 at 9:07 AM, Bruce Southey <bsouthey@gmail.com> wrote:

>  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@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
>>
>>
>
> _______________________________________________
> SciPy-Dev mailing listSciPy-Dev@scipy.orghttp://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.
>
> I don't think that is a reasonable assumption to make for someone just
learning how to use these packages.  When I started using these packages
myself about a year and a half ago, I remember not understanding the
difference between scipy and numpy (and pylab... and matplotlib...) because
they presented many of the same functions to me.  At the time, I figured
that I really was calling the same functions, just merely wrapped around the
other, or something like that.  It was quite confusing.  A time evolution of
my scripts would probably reveal some interesting insights into how my
understanding of scipy/numpy changed.

My point is that because there is so much shared functionality to the newbie
user, that they will tend to treat scipy and numpy as synonymous, and the
thought to check numpy's documentation will never even enter their minds.
Therefore, one should be careful to note in deprecation warnings that a
particular function is being deprecated because the functionality belongs in
another package.  That should raise awareness of the roles of the packages.

Ben Root
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/scipy-dev/attachments/20100603/1cf9aeac/attachment-0001.html 


More information about the SciPy-Dev mailing list