Steven D'Aprano writes:
> On Wed, Nov 17, 2021 at 02:26:16PM -0000, [email protected] 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
_______________________________________________
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/FFL3B6ZK7QGVAACZK775AOSHHM7SSDMT/
Code of Conduct: http://python.org/psf/codeofconduct/
