Brendan Barnwell writes:
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.
But for the students I teach, that's not what the `for` statement "does", it's an implementation detail. The `for` statement "iterates iterables", they know what those are because they're documented as "iterable", and that's all they need to know. I agree that the word "iterable" should be linked to its definition (which is *part* of the iterator protocol: calling `iter` on an iterable produces an iterator). But the implementations of `for` and sequence unpacking should IMO be described as *applications of* the iterator protocol where that protocol is documented. (It could be immediately preceding or following the documentation of `for`, but it's conceptually separate.)
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.
Even in the language reference, I disagree. It should be layered, so that people who need to know the syntax and external semantics of `for` -- which is complicated enough, since it includes `else`, `continue`, and `break` -- get *only* that in the section documenting `for`, with cross-references to implementation for people who are writing implementations. Much of what you want can be achieved by appropriate sequencing of sections, for people like you (and me!) who read language references front to back. But I believe making it the main organizing principle is going to overwhelm both students and teachers of the language.