This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author egebes
Recipients 4-launchpad-kalvdans-no-ip-org, John Parejko2, docs@python, egebes, eric.smith, pabouk, taleinat
Date 2021-12-29.12:47:39
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1640782059.96.0.205182478336.issue38401@roundup.psfhosted.org>
In-reply-to
Content
There is some confusion in the answers that I want to clear up:

"Attribute docstrings" were suggested in PEP 224 in August 2000 and rejected March 2001: https://www.python.org/dev/peps/pep-0224/

taleinat mentioned already PEP 258 from May 2001, which also contained "attribute docstrings" and was as well rejected.

At the same time - May 2001 - the well-known PEP 257 about docstring conventions came up and was accepted. It also mentions "attribute docstrings", but in a kind of restricted way (highlighting *** by me):

> String literals occurring elsewhere in Python code ***may also act as documentation***. They are ***not recognized*** by the Python bytecode compiler and are ***not accessible*** as runtime object attributes (i.e. not assigned to __doc__), ...
> Please see PEP 258, "Docutils Design Specification" [2], for a detailed description of attribute and additional docstrings.

The reference to the rejected PEP 258 does in my opinion not make the concept of "attribute docstrings" invalid, but indeed the restrictive wording (highlighted *** in the quote) defines their status, and it helps to explain the situation:

* Attribute docstrings are not supported by Python itself (no __doc__ etc.) -> that's why it is hard to add support for dataclass documentation in `help` as John Parejko suggested.

* It is totally fine to use attribute docstrings, since PEP 257 explicitly mentions them. Various tools support them.

* There is - as far as I can see it - no clear notion to differentiate between "official" docstrings and "inofficial" ones (attribute docstrings, additional docstrings). All of them are docstrings in the broader sense, though most times only the "official" ones are meant, and many don't even know about the "inofficial" ones.
History
Date User Action Args
2021-12-29 12:47:40egebessetrecipients: + egebes, taleinat, eric.smith, docs@python, John Parejko2, 4-launchpad-kalvdans-no-ip-org, pabouk
2021-12-29 12:47:39egebessetmessageid: <1640782059.96.0.205182478336.issue38401@roundup.psfhosted.org>
2021-12-29 12:47:39egebeslinkissue38401 messages
2021-12-29 12:47:39egebescreate