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.
--
Brendan Barnwell
"Do not follow where the path may lead. Go, instead, where there is no
path, and leave a trail."
--author unknown
_______________________________________________
Python-ideas mailing list -- python-ideas@python.org
To unsubscribe send an email to python-ideas-le...@python.org
https://mail.python.org/mailman3/lists/python-ideas.python.org/
Message archived at
https://mail.python.org/archives/list/python-ideas@python.org/message/HRS4BXHPGP27I32AVWRUZPYKW327IHCN/
Code of Conduct: http://python.org/psf/codeofconduct/
