Steven D'Aprano writes:
On Wed, Nov 17, 2021 at 02:26:16PM -0000, tmkehrenberg@gmail.com wrote:
@dataclass class A: """Docstring for class A.""" x: int """Docstring for x""" y: bool = True "Docstring for y"
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.
I agree it's a real problem. But I don't think it's a show-stopper. That is, the proposal as written also seems to be a near no-op from the point of view of backwards compatibility (I guess if you list the attributes of the class you would discover the new dunder).
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."""
True, but why would one want to, except to save the space? And for that, there's -OO.
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
Such a decorator moves the documentation even farther from its subjects? And doesn't simply class A: """Class docstring.""" __attrdoc__ == {"x": "Docstring for x", "y": "Docstring for y"} x: int y: bool = True do the trick? Or if you just like decorating (bear with me now, this is revolutionary): @standard_class_docstring_parser class A: """ Class docstring. x: Docstring for x y: Docstring for y """ x: int y: bool = True which must exist somewhere already (I'm sure Sphinx has a nice fancy function for this). I guess that brings me all the way to -1 on the proposal as is; the "below the attribute" syntax isn't sufficiently attractive to justify syntax. Steve