On Wed, Dec 30, 2020 at 8:49 AM Brendan Barnwell brenbarn@brenbarn.net wrote:
To my mind, every time a change is made to Python behavior there mustbe a corresponding change to the main documentation describing the change. I would go so far as to say that the lack of such documentation updates should be a blocker on the release of the feature. Features without complete documentation in a straightforward place on python.org/docs (not the PEPs!) should not be shipped.
It's not that simple. As one example, consider zipapp:
https://docs.python.org/3/whatsnew/3.5.html#whatsnew-zipapp
It existed for a long time before that, and technically WAS documented, but nobody knew about it. Would you say that Python would have been better off leaving this feature languishing on the bug tracker for lack of adequate documentation? What does "adequate" even mean? (Or to use your term, "complete"? Perhaps even harder to define.)
Documentation bugs are bugs to be fixed, just like any other. Rather than complaining that this should have prevented the feature from being released, just propose an improvement. Where should this be documented? How should it be worded?
(I'd contribute actual wording myself, but I don't know the details of the feature well enough. TBH, I only ever use ** with actual dictionaries.)
ChrisA