On Wed, Dec 08, 2021 at 11:50:55AM -0000, [email protected] 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 -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-ideas.python.org/
Message archived at
https://mail.python.org/archives/list/[email protected]/message/AUWFRUGDQC4DGSUURYAQSJOQ75NKXEQT/
Code of Conduct: http://python.org/psf/codeofconduct/
