[docs] [issue13235] logging.warn() is not documented

Ezio Melotti report at bugs.python.org
Fri Oct 21 04:28:27 CEST 2011


Ezio Melotti <ezio.melotti at gmail.com> added the comment:

I think it's better to avoid "deprecations by missing documentation" and document explicitly if something is deprecated.
What happens is that people working on some old code find the deprecated method, check the doc to see what it does, don't find anything, get puzzled for a while until they figure out how it works, and then use it.
If they find it and see that is deprecated they will stop using it and start using the right method.
While it's true that new users don't need to know that there's a deprecated method, it's unlikely that they will start using it, so documenting deprecated methods makes more good than harm.
If you want to remove it eventually you'll also have to go through an actual deprecation process with warnings.

----------
nosy: +ezio.melotti
resolution: invalid -> 
stage:  -> needs patch
versions: +Python 3.2

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13235>
_______________________________________


More information about the docs mailing list