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.
The unpacking "protocol" (or whatever we call it) should be documented right where function call syntax is documented.
That's going to be a bit obscure for people who want to understand unpacking:
a, b, *extras, z = values
__getitem__ should be documented right where the [] syntax is documented.
That's a bit confusing for people who know the method name but don't know what syntax uses it. And its a lot confusing for people who just want to know what subscripting means but don't care about the dunder methods used to implement it.
The descriptor protocol should be documented right where attribute access syntax is documented.
And that's quite hostile to those who want a simple high-level overview of what attribute access does without having a low-level and very advanced feature, descriptors, shoved down their throat.
Brendan, I applaud your zeal in wanting to fix the Python docs, but things which are no-brainer improvements to *you* will be no-brainer regressions to others.
In particular, the Python docs aren't a dead-tree book, they are a hypertext document. There's no need to have features documented "right where" related features are documented, because that leads to needing everything documented in one place:
- subscripting `[]` needs to have mappings and sequences documented right there;
- mappings need to have hash documented right there;
- sequences need to have integers and the `__index__` dunder documented right there
- integers need to have the numeric tower documented right there
- which needs ABCs to be documented right there
and because everything in Python is connected to everything else, the entire language and std lib needs to be on one page.
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.