On 2020-12-29 13:54, Chris Angelico wrote:
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?
Well, I did propose it, for this particular case, in a part of the message you didn't quote.
But I think ultimately to do it right the documentation needs a structural overhaul. The way it is now tries to separate "language reference" and "library reference", where the former seems to mainly be describing syntax, with other stuff shunted off into opaquely-titled sections like "data model". But I think that is confusing
So, to give an example, the iterator protocol should be documented right where the `for` statement is documented, and it should be explicitly framed as "this is the definition of what the `for` statement does", not something separate. The unpacking "protocol" (or whatever we call it) should be documented right where function call syntax is documented. __getitem__ should be documented right where the [] syntax is documented. The descriptor protocol should be documented right where attribute access syntax is documented. And so on. In other words, the "language reference" should be more or less a catalog of syntactic features with in-situ definitions of their semantics as the invocation of a particular protocol.
I think the way Python handles these things as a language is one of its greatest features. Basically Python is a sort of syntactic framework on which you can hang various implementations by overriding dunders, and that's very powerful. So it's unfortunate that that isn't used as the main organizing principle of the documentation.