[New-bugs-announce] [issue41787] adding PEP references to documentation

[Cameron Simpson]

New submission from Cameron Simpson <cs at cskk.id.au>:

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.

----------
assignee: docs at python
components: Documentation
messages: 376914
nosy: cameron, docs at python
priority: normal
severity: normal
status: open
title: adding PEP references to documentation

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue41787>
_______________________________________