Allow attributes to be documented using comments above the attribute

[samuelcolvin]

(Please accept my apology if this is already discussed or resolved somewhere, I've looked but couldn't find anything)

Is your feature request related to a problem? Please describe.

Currently when documenting attributes (in google style docstrings), I use the following:

class Foo:
    my_attr: int = 42
    """This is the documentation about `my_attr`"""

I don't find this very intuitive.

Describe the solution you'd like

It would be great if comments before the attribute could be used to document it. AFAIK this is support in sphinx, as follows:

class Foo:
    #: This is the documentation about `my_attr`
    my_attr: int = 42

It would be great if this style could be supported while otherwise still using google style docstrings?

I've just tried this and neither pycharm or black complain about the lack of space after the # - I guess because they know about the sphinx style.

Describe alternatives you've considered

I guess we could use docstrings above the attribute, but then the association of attributes would be unclear or would change implicitly based on a configuration parameter, which would not be good.

Additional context

I'm going to be using mkdocstrings to document pydantic v2 and perhaps pydantic-core, would be great if we could support this before I start in a few weeks if you agree it's acceptable?

[samuelcolvin]

I've just had a try and it seems that even with docstring_style: sphinx, comments above attributes are not being picked up, so I guess this would need to be a new feature?

[pawamoy]

This has been partially discussed, but I myself don't remember where, so no problem, and thanks for the feature request 😊

So, supporting docstrings above attributes is a no-go. It would indeed make things confusing, especially for the first docstring in a module: is it the module's docstring, or the first attribute's docstring?

About #: comments: I'm not sure it's Sphinx-specific 🤔 Do you have any links explaining where they come from?
Supporting these comments is quite difficult because ast would simply skip those, even with type_comments enabled. It means that we need to tokenize the code to get these comments. We do use the tokenize module already, but only for compatibility with Python 3.7, in which ast does not return ending line numbers of AST nodes.

We could consider adding an option to support these comments, using tokenize, and warn users that it could impact performance (no data on that part yet). It's not a high priority to me though, since it seems to just be a cosmetic preference?

About intuitiveness of docstrings below attributes: maybe you'll find it consistent with how docstrings are added below signatures of functions/classes?

Also note that instead of documenting attributes individually, you can document them using an Attributes section on the class' docstring, though the attributes would not have a ToC entry in your built docs then, so I understand it's not always a good workaround.

[samuelcolvin]

Interesting, I get where you're coming from.

I see the "docstring after function definition" argument, but I still don't find it very as intuitive.

Here's the link to the sphinx docs on attributes, you'll have to scroll down.

Overall, I'd still really like this feature, but I understand why it's not a priority.

[pawamoy]

OK, noted 🙂 Maybe someone with tokenize experience will chime in! I myself had trouble using it, and I don't even think I got the code right (ending line numbers are still off on Python 3.7).

Thanks for the link!