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 -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-ideas.python.org/
Message archived at
https://mail.python.org/archives/list/[email protected]/message/6J54T2BBDASJQQEHVN7JTAHRUVETKBLB/
Code of Conduct: http://python.org/psf/codeofconduct/
