[New-bugs-announce] [issue40045] Make "dunder" method documentation easier to locate

[Kyle Stanley]

New submission from Kyle Stanley <aeros167 at gmail.com>:

In a recent python-ideas thread, the rule of dunder methods being reserved for Python internal usage only was brought up (https://mail.python.org/archives/list/python-ideas@python.org/message/GMRPSSQW3SXNCP4WU7SYDINL67M2WLQI/), due to an author of a third party library using them without knowing better. Steven D'Aprano linked the following section of the docs that defines the rule: https://docs.python.org/3/reference/lexical_analysis.html#reserved-classes-of-identifiers. 

When I had attempted to search for the rule in the documentation (prior to the above discussion), I noticed that it was rather difficult to discover because it was written just as "System-defined names" with no mention of "dunder" (which is what the dev community typically refers to them as, at least in more recent history).

To make it easier for the average user and library maintainer to locate this section, I propose changing the first line to one of the following:

1) System-defined names, also known as "dunder" names.
2) System-defined names, informally known as "dunder" names.

I'm personally in favor of (1), but I could also see a reasonable argument for (2). If we can decide on the wording, it would make for a good first-time PR to the CPython docs.

----------
assignee: docs at python
components: Documentation
keywords: easy, newcomer friendly
messages: 364832
nosy: aeros, docs at python
priority: normal
severity: normal
status: open
title: Make "dunder" method documentation easier to locate
type: enhancement
versions: Python 3.8, Python 3.9

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