In short: class attributes cannot have doc strings in the way that classes and functions have.

To avoid confusion, the term property has a specific meaning in python. What you're talking about is what we call class attributes. Since they are always acted upon through their class, I find that it makes sense to document them within the class' doc string. Something like this:

class Albatross(object):
    """A bird with a flight speed exceeding that of an unladen swallow.

    Attributes:
        flight_speed     The maximum speed that such a bird can attain.
        nesting_grounds  The locale where these birds congregate to reproduce.
    """
    flight_speed = 691
    nesting_grounds = "Throatwarbler Man Grove"

I think that's a lot easier on the eyes than the approach in your example. If I really wanted a copy of the attribute values to appear in the doc string, I would put them beside or below the description of each attribute.

Keep in mind that in Python, doc strings are actual members of the objects they document, not merely source code annotations. Since class attribute variables are not objects themselves but references to objects, they have no way of holding doc strings of their own. I guess you could make a case for doc strings on references, perhaps to describe "what should go here" instead of "what is actually here", but I find it easy enough to do that in the containing class doc string.

Answer from ʇsәɹoɈ on Stack Overflow
Top answer
1 of 6
135

In short: class attributes cannot have doc strings in the way that classes and functions have.

To avoid confusion, the term property has a specific meaning in python. What you're talking about is what we call class attributes. Since they are always acted upon through their class, I find that it makes sense to document them within the class' doc string. Something like this:

class Albatross(object):
    """A bird with a flight speed exceeding that of an unladen swallow.

    Attributes:
        flight_speed     The maximum speed that such a bird can attain.
        nesting_grounds  The locale where these birds congregate to reproduce.
    """
    flight_speed = 691
    nesting_grounds = "Throatwarbler Man Grove"

I think that's a lot easier on the eyes than the approach in your example. If I really wanted a copy of the attribute values to appear in the doc string, I would put them beside or below the description of each attribute.

Keep in mind that in Python, doc strings are actual members of the objects they document, not merely source code annotations. Since class attribute variables are not objects themselves but references to objects, they have no way of holding doc strings of their own. I guess you could make a case for doc strings on references, perhaps to describe "what should go here" instead of "what is actually here", but I find it easy enough to do that in the containing class doc string.

2 of 6
108

The other answers are very outdated. PEP-257 describes how you can use docstrings for attributes. They come after the attribute, weirdly:

String literals occurring elsewhere in Python code may also act as documentation. They are not recognized by the Python bytecode compiler and are not accessible as runtime object attributes (i.e. not assigned to __doc__), but two types of extra docstrings may be extracted by software tools:

  1. String literals occurring immediately after a simple assignment at the top level of a module, class, or __init__ method are called “attribute docstrings”.
class C:
    "class C doc-string"

    a = 1
    "attribute C.a doc-string (1)"

    b = 2
    "attribute C.b doc-string (2)"

It also works for type annotations like this:

class C:
    "class C doc-string"

    a: int
    "attribute C.a doc-string (1)"

    b: str
    "attribute C.b doc-string (2)"

VSCode supports showing these.

🌐
Python
docs.python.org › 2.0 › doc › classes.html
4 Document Classes
The manual documents are larger and are used for most of the standard documents. This document class is based on the standard LATEX report class and is formatted very much like a long technical report. The Python Reference Manual is a good example of a manual document, and the Python Library ...
🌐
Python
docs.python.org › 2.2 › doc › classes.html
5 Document Classes
The manual documents are larger and are used for most of the standard documents. This document class is based on the standard LATEX report class and is formatted very much like a long technical report. The Python Reference Manual is a good example of a manual document, and the Python Library ...
🌐
Lsst
developer.lsst.io › v › DM-15183 › python › numpydoc.html
Documenting Python APIs with Docstrings — LSST DM Developer Guide DM-15183 documentation
MAX_ITER = 10 """Maximum number of iterations (`int`). """ class MyClass(object): """Example class for documenting attributes. """ x = None """Description of x attribute.
🌐
Real Python
realpython.com › documenting-python-code
Documenting Python Code: A Complete Guide – Real Python
July 17, 2026 - These are built-in strings that, when configured correctly, can help your users and yourself with your project’s documentation. Along with docstrings, Python also has the built-in function help() that prints out the objects docstring to the console. Here’s a quick example: ... >>> help(str) Help on class str in module builtins: class str(object) | str(object='') -> str | str(bytes_or_buffer[, encoding[, errors]]) -> str | | Create a new string object from the given object.
🌐
Programiz
programiz.com › python-programming › docstrings
Python Docstrings (With Examples)
Let's take an example. def multiplier(a, b): """Take two numbers and return their product.""" return a*b · Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description. The PEP 257 document provides the standard conventions to write multi-line docstrings for various objects. ... The docstrings for Python Modules should list all the available classes...
🌐
Lsst
developer.lsst.io › v › DM-5063 › docs › py_docs.html
Documenting Python Code — LSST DM Developer Guide latest documentation
When describing an argument in the description, enclose the name of the variable in single backticks (the default role in reST, which is Python-aware in docstrings). For the parameter types, be as precise as possible. Parameters ---------- filename : str Description of `filename`. copy : bool Description of `copy`. dtype : data-type Description of `dtype`. iterable : iterable object Description of `iterable`. shape : int or tuple of int Description of `shape`. files : list of str Description of `files`. For instances of classes, provide the full namespace to the class.
🌐
DataCamp
datacamp.com › tutorial › docstrings-python
Python Docstrings Tutorial : Examples & Format for Pydoc, Numpy, Sphinx Doc Strings | DataCamp
February 14, 2025 - You'll be looking over the example of a popular format for documentation string available with their use. At first, you will see the Sphinx Style in detail, and then you can easily follow along with other formats as well. Sphinx is the easy and traditional style, verbose, and was initially created specifically for Python Documentation. Sphinx uses a reStructured Text, which is similar in usage to Markdown. class Vehicle(object): ''' The Vehicle object contains lots of vehicles :param arg: The arg is used for ...
Find elsewhere
🌐
Readthedocs
sphinxcontrib-napoleon.readthedocs.io › en › latest › example_google.html
Example Google Style Python Docstrings — napoleon 0.7 documentation
Args: param1 (str): Description of `param1`. param2 (:obj:`int`, optional): Description of `param2`. Multiple lines are supported. param3 (:obj:`list` of :obj:`str`): Description of `param3`. """ self.attr1 = param1 self.attr2 = param2 self.attr3 = param3 #: Doc comment *inline* with attribute #: list of str: Doc comment *before* attribute, with type specified self.attr4 = ['attr4'] self.attr5 = None """str: Docstring *after* attribute, with type specified.""" @property def readonly_property(self): """str: Properties should be documented in their getter method.""" return 'readonly_property' @p
🌐
Lsst
developer.lsst.io › v › DM-7919 › docs › py_docs.html
Documenting Python APIs — LSST DM Developer Guide latest documentation
Parameters ---------- values : iterable Python iterable whose values are summed. Returns ------- sum : `float` Sum of `values`. """ pass · Like method and function docstrings, the docstring should immediately follow the class definition, without a blank space.
🌐
Medium
medium.com › @syedar.sohail › docstring-and-why-is-it-important-python-classes-modules-and-functions-95fee5247ff5
Docstring and why is it important ? — Python Classes, Modules and Functions | by Sohail | Medium
October 30, 2022 - “It doesn’t matter how good your software is, because if the documentation is not good enough, people will not use it.”— Daniele Procida · This time the results are very helpful, Joe can now understand what the “check_id”, “signatures” and little description about values that could be in the class. In the above example the docstrings were used in both the class “iphone_entry”and the methods “check_id”, “signatures” inside the class.
🌐
GeeksforGeeks
geeksforgeeks.org › python-docstrings
Python Docstrings - GeeksforGeeks
August 2, 2024 - ... def multiply_numbers(a, b): """ Multiplies two numbers and returns the result. Args: a (int): The first number. b (int): The second number. Returns: int: The product of a and b. """ return a * b print(multiply_numbers(3,5)) ... Numpydoc-style ...
🌐
SourceForge
epydoc.sourceforge.net › manual-docstring.html
Python Docstrings - Epydoc
class A: x = 22 """Docstring for class variable A.x""" def __init__(self, a): self.y = a """Docstring for instance variable A.y · Variables may also be documented using comment docstrings.
🌐
Read the Docs
python-docx.readthedocs.io › en › latest › api › document.html
Document objects — python-docx 1.2.0 documentation
Return a Document object loaded from docx, where docx can be either a path to a .docx file (a string) or a file-like object.
🌐
Readthedocs
pydoctor.readthedocs.io › en › latest › codedoc.html
How to Document Your Code — pydoctor documentation
Documentation can also be put into a comment with special formatting, using a #: to start the comment instead of just #. Comments need to be either on their own before the definition, OR immediately after the assignment on the same line. The latter form is restricted to one line only.: var = True #: Doc comment for module attribute. class Foo: #: Doc comment for class attribute Foo.bar.
🌐
sqlpey
sqlpey.com › python › top-4-ways-to-solve-how-to-document-class-attributes-in-python
Top 4 Ways to Solve How to Document Class Attributes in Python
November 6, 2024 - The properties provide a neatly packaged way to access and document attributes: class Fish: def __init__(self): self._length = 0 @property def length(self): """Length of the fish in centimeters.""" return self._length @length.setter def length(self, value): self._length = value ## Example Usage goldfish = Fish() goldfish.length = 10 print(goldfish.length) # Output: 10 print(Fish.length.__doc__) # Output: Length of the fish in centimeters.
🌐
Noirlab
datalab.noirlab.edu › docs › manual › DevGuide › DocumentingPythonAPIswithDocstrings › DocumentingPythonAPIswithDocstrings.html
3.2. Documenting Python APIs with Docstrings — Data Lab documentation
The __init__ method never has a docstring since the class docstring documents the constructor. Here’s an example of a more comprehensive class docstring with Short Summary, Parameters, Raises, See Also, and Examples sections:
🌐
PyPI
pypi.org › project › class-doc
class-doc
JavaScript is disabled in your browser · Please enable JavaScript to proceed · A required part of this site couldn’t load. This may be due to a browser extension, network issues, or browser settings. Please check your connection, disable any ad blockers, or try using a different browser
🌐
Stack Overflow
stackoverflow.com › questions › 63280557 › python-docx-library-how-to-extend-the-class-document
python-docx library - How to extend the class "Document' - Stack Overflow
For example - below does not work · from docx.document import Document as doc1 class doc_new(doc1): def new_prop(self, q): self.name = q return self.name document = Document() x = document.new_prop("John") print(x) ... The Document object returned ...
🌐
Python How Tos
campbell-muscle-lab.github.io › howtos_Python › pages › documentation › best_practices › best_practices.html
Documentation Best Practices - Python How Tos
The Raises section is for documenting any errors the function might raise if any problems are encountered during its executation. If the function doesn’t raise any errors, don’t add the Raises section. ... class ClassName(BaseClassName): """[one line summary] [multiple line summary if needed] """ def __init__(self, first_param, second_param): """[one line summary] [multiple line summary if needed] Parameters ---------- [first param name] : [type] [description] [second param name] : [type] [description] [repeat for all parameters in the init function] Raises ------ [EXCEPTION THIS FUNCTION RAISES] [Why this function raises the exception] """