Message376914
Add rationale for __length_hint__ and link to PEP 424, per the discussion here:
https://mail.python.org/archives/list/python-dev@python.org/thread/HXNFMIEZH73MXYEBP4TDIK3KFPYJ4QKR/#CXBEWAYSCAZCU7QABRBTKNVPDM3LELUM
Once the phrasing and directives are agreed, continue to chase other references in the docs.
This will produce multiple small PRs, possibly one per PEP as chased.
Phrasing:
I intend to amend the "New in version V." lines to become "New in version V, originally specified by PEPNNN." with a link to the PEP on "PEPNNN". I'm tempted to make "version V" also a link to its Whats New page; that will make for a bit more visual noise but seems pertinent.
The other thing I'd like to consider is a _single sentence_ in the docs identifying the main motivating use case for the feature. The __length_hint__ docs are a prime example here - the purpose of the feature is not mentioned, merely its semantics. While a feature can be used for many purposes, knowing why it was introduces brings a lot of cognitive benefit to the reader. |
|
Date |
User |
Action |
Args |
2020-09-14 22:49:01 | cameron | set | recipients:
+ cameron, docs@python |
2020-09-14 22:49:01 | cameron | set | messageid: <1600123741.16.0.294796218957.issue41787@roundup.psfhosted.org> |
2020-09-14 22:49:01 | cameron | link | issue41787 messages |
2020-09-14 22:49:00 | cameron | create | |
|