[SciPy-Dev] Warning of deprecation in doc's ?
Wed Jun 2 23:17:51 CDT 2010
On Wed, Jun 2, 2010 at 11:05 PM, David Goldsmith <firstname.lastname@example.org>wrote:
> On Wed, Jun 2, 2010 at 8:28 PM, Benjamin Root <email@example.com> 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
> pydocweb (our doc editing Wiki) does do something like that in that it
> automatically prepends the function signature to the docstring (at least I
> think it's pydocweb that's doing it), so I think it's possible in
> principle. code.google.com/p/pydocweb hosts a ticketing system (the
> "Issues" tab) - may I ask you to go there and file an "enhancement" ticket
> for this - the worst that can happen is that someone (probably Pauli V.)
> will mark it as "will not do" with some sort of explanation as to why.
> That said, pydocweb has a long backlog of open issues, and this is not the
> highest priority among them. Accordingly, we probably shouldn't wait for it
> to solve our problem, i.e., we should still decide on where and how to note
> this, and do it manually when we encounter the situation. So, so far we
> have one "vote" for "yes, near the beginning." :-)
> I will look into that tomorrow. And I certainly agree that we should not
wait until pydocweb presents us a solution. We should certainly follow some
sort of standard way to mark/tag/denote these deprecation warnings, that way
'grep' can still be a very valuable tool here.
>> On Wed, Jun 2, 2010 at 10:07 PM, David Goldsmith <firstname.lastname@example.org
>> > wrote:
>>> On Wed, Jun 2, 2010 at 7:22 PM, Vincent Davis <email@example.com>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
>>> 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?
>>> SciPy-Dev mailing list
>> SciPy-Dev mailing list
> 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
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the SciPy-Dev