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. -- Steve _______________________________________________ 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/6J54T2BBDASJQQEHVN7JTAHRUVETKBLB/ Code of Conduct: http://python.org/psf/codeofconduct/