[docs] [issue37563] Documentation - default for StreamHandler
report at bugs.python.org
Sat Jul 13 04:38:13 EDT 2019
Jonathan <bugreports at lightpear.com> added the comment:
> The devil is in the detail. If stream=sys.stderr is specified, that takes effect at import time. If stream=None is specified and the implementation chooses to treat that as sys.stderr, that takes effect at the time of the call. The two are not equivalent.
But this isn't what the prose says at all. You're right, the prose clearly say that the default is sys.stderr, however the code doesn't show that, and many people won't read the prose (I don't a lot of the time), they'll only look at the code snippet because that's all they think they need. The code-snippet claims that the default is None, which from a user perspective isn't true.
Again I point out that the documentation is for users, not implementers. We users Do. Not. Care. about how wonderfully clever your implementation is, we care about how it actually works. Whatever Rube-Goldbergian implementation details there are behind the scenes are of no interest to us.
There's a standard for documenting defaults for keyword arguments, I would ask that it please be used consistently to help us users.
Fine, lets try this another way - does anyone else have opinions on this? What's the convention for documentation defaults?
Python tracker <report at bugs.python.org>
More information about the docs