On Wed, Nov 17, 2021 at 02:26:16PM -0000, tmkehrenb...@gmail.com wrote:
> @dataclass
> class A:
> """Docstring for class A."""
> x: int
> """Docstring for x"""
> y: bool = True
> "Docstring for y"
>
> It is a bit awkward that the docstring is *below* the definition of the
> attribute, but it can't be put above because it could be confused for
> the class docstring.
Function and class docstrings follow *below* the function/class
signature, so I don't think that's a problem.
However a real problem is that bare strings like that are already legal,
although only as a no-op. People sometimes use them as multiline
comments.
So we would have no real way of distinguishing between these cases:
class A:
"""Docstring for class A."""
x: int
"""Docstring for x"""
y: bool = True
"""Just a comment."""
Making such strings syntactically meaningful would be a breaking change,
although one with a very small impact. (Some strings which were
previously ignored by the interpreter will now be kept in memory as
docstrings.)
> My proposal would be to just enshrine this syntax as the syntax for
> attribute docstring, and to make them available at runtime. They would
> be stored in a dictionary like the type annotations. For example like
> this:
>
> A.__attrdoc__ == {"x": "Docstring for x", "y": "Docstring for y"}
You could get that same effect with a decorator:
@attrdoc(x="Doctring for x",
y="Doctring for y")
class A:
"""Class docstring."""
x: int
y: bool = True
There's some duplication of the names, which is sad, but otherwise I
don't mind it.
--
Steve
_______________________________________________
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/2F7CZRNSEEWRIBUFTTR3CBTLWO6APKJW/
Code of Conduct: http://python.org/psf/codeofconduct/
