Erik Gebeshuber <erik.gebeshu...@gmx.net> added the comment:
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. ---------- nosy: +egebes _______________________________________ Python tracker <rep...@bugs.python.org> <https://bugs.python.org/issue38401> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
