On Wed, Dec 08, 2021 at 11:50:55AM -0000, tmkehrenb...@gmail.com wrote: > A few weeks ago, I proposed on this mailing list to write docstrings for > class attributes like this: > > @dataclass > class A: > x: int > """Docstring for x.""" > ... is a normal string, except that it is stored in __attrdoc__ when > used inside a class. It is stored with the name of the variable > *below* it as the key.
I like the idea of standardizing a name like __attrdoc__. Broadly, I think it is a good idea to enable attribute docstrings. But I think bare strings are probably not a good idea, and I definitely think adding more string prefixes is not a good idea. Of the various ideas noted here and before, I think the one that resonates with me the most is to add a docstring parser (and possibly allow others to write their own if they write their docstrings in a different way). This would look like this. # add a docstring parser decorator @parse_attrdoc_from_docstring class A: """ Class docstring. x: Docstring for x y: Docstring for y """ x: int y: bool = False And functionally, that would be equivalent to doing the following directly. # or explicitly set __attrdoc__ class B: """Class docstring.""" __attrdoc__ = { "x": "Docstring for x", "y": "Docstring for y", } x: int y: bool = False If someone wanted to document an already written library and has a different (but consistent) convention in their class docstrings for class variables, then it shouldn't be too hard to modify the default parser. Maybe? - DLD _______________________________________________ Python-ideas mailing list -- python-ideas@python.org To unsubscribe send an email to python-ideas-le...@python.org https://mail.python.org/mailman3/lists/python-ideas.python.org/ Message archived at https://mail.python.org/archives/list/python-ideas@python.org/message/AUWFRUGDQC4DGSUURYAQSJOQ75NKXEQT/ Code of Conduct: http://python.org/psf/codeofconduct/