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

[Vincent Davis]

On Wed, Jun 2, 2010 at 10:05 PM, David Goldsmith
<d.l.goldsmith at gmail.com> wrote:
> On Wed, Jun 2, 2010 at 8:28 PM, Benjamin Root <ben.root at ou.edu> 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.
  So, so far we

> have one "vote" for "yes, near the beginning." :-)
>

I vote near the beginning for the reasons Benjamin notes "the user
might not scroll all the way down past the feature
that they found"

And including as much reference to the replacement as possible (a link
to the doc?, function name......) Make it easy to find its
replacement.

Vincent


> DG
>
>
>>
>> On Wed, Jun 2, 2010 at 10:07 PM, David Goldsmith <d.l.goldsmith at gmail.com>
>> wrote:
>>>
>>> On Wed, Jun 2, 2010 at 7:22 PM, Vincent Davis <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
>>> 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)
>
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
>