-
Notifications
You must be signed in to change notification settings - Fork 767
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Class attribute documentation? #1576
Comments
We emulate |
@brettcannon, out of curiosity, how would you typically provide documentation for a class or instance variable? A string literal on the line before the variable's first usage? On the line after (consistent with docstrings in class and function declarations)? On the same line, as an end-of-line comment? Do you think there's sufficient consistency in how this is done in Python code for pyright to assume there's a standard? |
@erictraut As explained in the original discussion, it's indicated in PEP 257
So basically: def __init__(self):
self.foo = 33
"""Description of foo.""" I'm not sure it's used a lot but it's specified somewhere. Another way would be to parse the class docstring but I guess it would be a much bigger change. |
To be honest, I am not aware of any specific standard around attribute documentation. I actually didn't even know about the line from PEP 257 until @Holt59 pointed it out to me. |
Yeah, I wasn't aware of that either. I don't recall ever seeing an "attribute docstring" used in Python code. |
As a bump to this issue, I actually just ran into this, myself. One of the specific use-cases for this kind of functionality is in the definition of constants modules. Let's say you have a lot of constants you need to make use of in your program or library, and you would like other developers (or yourself...) to be able to quickly look up detailed information about the nature of these constants (think scientific computing). One could opt for a verbose strategy of classing... class _BestNumbers:
"""A very well documented class."""
@property
def the_best_number(self) -> int:
"""The best number known.
This extensive documentation explains why this particular
value is the best. It all started when....
"""
return 42
BestNumbers = _BestNumbers() However, a less cumbersome method might be to just define such sets of constants within their own module. But in this case, while PEP 257 illustrates how one could document such variables for those visiting the source definition, unless the language server supports PEP 257, those docstrings aren't carried forward to where the developer actually needs it. # Defined within some constants/best_numbers.py
THE_BEST_NUMBER: int = 42
"""The best number known.
This extensive documentation explains why this particular
value is the best. It all started when....
""" |
@eric-tramel, thanks for the input. Yes, what you say makes sense in theory. In practice, I've never seen attribute docstrings (as defined in PEP 257) used in any Python libraries. Are you aware of any examples of their use? This might be a chicken-vs-egg situation where library authors will start to include attribute docstrings in more cases if pylance and other tools start to support them. |
Not public ones, sorry @erictraut :) I would think it is more chicken-and-egg. I know that I would write simpler code if it meant that others using it could get information more easily. But if I have to contort with classes to do it, then I use the |
Support for attribute docstrings in the completion provider will be included in the next release of pyright and pylance. |
This issue has been fixed in version 2021.7.6, which we've just released. You can find the changelog here: https://github.com/microsoft/pylance-release/blob/main/CHANGELOG.md#202176-28-july-2021 |
Sorry, I know this has been closed for a while, but... THIS THREAD BLEW MY MIND. I had no idea this was a thing. Now I do. To whoever worked on this: you're amazing. |
Necro-posting, but anyway. This style
was explicitly rejected by Guido https://peps.python.org/pep-0224/. Maybe that's why nobody uses it. Wide usage (and support from sphinx) has
as for example seen https://github.com/pytest-dev/pytest/blob/main/src/_pytest/reports.py#L272 https://github.com/pallets/flask/blob/main/src/flask/app.py#L207 🤷 The |
Is there an existing feature-request issue to add support for the style that @kaste mentioned above? It was just asked about on Stack Overflow: Show Python docstring for instance attribute in VS Code. |
I don't believe so. But if it's not part of standard doc strings, it would probably take a lot of up votes for us to add it. |
Discussed in microsoft/vscode-python#16736
Originally posted by Holt59 July 19, 2021
I'd like to know how I can get class attribute documentation on hover/completion, similar to what I would get with the docstring of a property:
How can I get proper documentation (on hover/completion) for
bar
without using a property?Note: I'm asking here since I don't know if it is something specific to this extension or to the server (I'm using Pylance).
The text was updated successfully, but these errors were encountered: