New submission from Cameron Simpson <c...@cskk.id.au>:
Add rationale for __length_hint__ and link to PEP 424, per the discussion here: https://mail.python.org/archives/list/python-...@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. ---------- assignee: docs@python components: Documentation messages: 376914 nosy: cameron, docs@python priority: normal severity: normal status: open title: adding PEP references to documentation _______________________________________ Python tracker <rep...@bugs.python.org> <https://bugs.python.org/issue41787> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
