On 2020-12-29 16:18, Steven D'Aprano wrote:
On Tue, Dec 29, 2020 at 02:20:05PM -0800, Brendan Barnwell wrote:
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.
Hmmm, that's going to be a bit confusing for people who want to understand iter() and next() but don't care about for loops directly.
With regard to this and your other comments, I can see that that could be useful in some cases. But the important points are: 1) if the for statement uses the iterator protocol (which it does), the part of the documentation where the for statement is defined absolutely must link to the docs on the iterator protocol; and 2) the details of how `for` uses the protocol must be explained in full in the docs for `for`.
I totally agree with you that the connections between features, and detailed information about protocols and dunders can sometimes be hard to find, but I think that the solution is not a complete redesign of the docs, but more hyperlinks and See Alsos.
I would go slightly further than that though. It's not just "see alsos". It can be hyperlinks, but what needs to be made clear is that the hyperlinks are to DEFINITIONAL information where that is the case. In other words, the `for` statement docs need to say that the operation of the `for` statement is DEFINED by the iterator protocol. Now yes, if that definiton has many nooks and crannies we can factor those out into a separate page. But the way that `for` uses the iterator should indeed be spelled out. For instance, right now it says:
An iterator is created for the result of the expression_list. The suite is then executed once for each item provided by the iterator, in the order returned by the iterator. Each item in turn is assigned to the target list using the standard rules for assignments (see Assignment statements), and then the suite is executed.
What I'm saying is it should say something like:
An iterator (link to iterator protocol here) is created by calling iter() on the result of the expression_list. For each loop iteration, next() is called on the iterator, then the resulting value is assigned to the target list using the standard rules for assignment (link to assignment here), and then the suite is executed.
Now, you're right that's a bit different from it maybe sounded like in my message before. I'm not necessarily saying that the entire definition of next and iter needs to be in there. But what I am saying is that the nuts and bolts of how `for` uses the protocol DO need to be in there. Things like "returned by the iterator" (which is not clear in the terminology of the iterator protocol) should be replaced by things like "returned by calling next() on the iterator" or "returned by the iterator's __next__ method".
My point here is really more about the docs on other parts of Python rather than the documentation of the iterator protocol itself (or other such protocols). You're right that they need to be integrated, but it's not solely a matter of providing links; I think there needs to be considerably more detail about the precise way in which syntactic features make use of these protocols. (Or in some cases less detail may be needed; for instance, right now the `for` docs include a little note about "modifying the sequence" while it is being iterated over; this doesn't belong there because the for statement doesn't care about sequences, but only about the iterator protocol.)
For the same reason, I'm less concerned about people who want to know about iter() and next() themselves. That information is nice to have, and it should be there in an easily-findable section of the docs for sure. But `for` is a basic language construct, and it's in the documentation of those basic language constructs where we need that clarity about how they interact with the protocols.
I don't think this would require a complete redesign of the docs, because sure, a lot of it could stay the same, but what I meant by "overhaul" is that some restructuring (not just changing of wording) is necessary. For instance, protocols like iterator, descriptor, etc., which, as you say, may be used in various ways, really need their own section if we're going to be referring to them via hyperlinks. But more than that, I think a lot of the documentation on basic stuff like loops, attribute access, even mathematical operators, needs to be reconceptualized so that it couches the entire description in terms of the protocols that are actually used. It's not just a few links here and there.