🌐
Programiz
programiz.com › python-programming › docstrings
Python Docstrings (With Examples)
For example, "I am a single-line comment" ''' I am a multi-line comment! ''' print("Hello World") Note: We use triple quotation marks for multi-line strings. ... As mentioned above, Python docstrings are strings used right after the definition of a function, method, class, or module (like in ...
🌐
Python
peps.python.org › pep-0257
PEP 257 – Docstring Conventions | peps.python.org
The entire docstring is indented the same as the quotes at its first line (see example below). Insert a blank line after all docstrings (one-line or multi-line) that document a class – generally speaking, the class’s methods are separated from each other by a single blank line, and the ...
Discussions

python - Should I list class methods in the class docstring? - Stack Overflow
Also the wording in the PEP to me means that the class docstring "should" list the public methods, but not describe them in any other way.(This is also how the above standard library example does it.) But as said, I would never even do that, since the code speaks for itself and that kind of ... More on stackoverflow.com
🌐 stackoverflow.com
What's the best guide/model to writing good docstrings for modules/classes/methods?
Check out this stack overflow answer . I won't copy paste the good info from that, but I would highlight this: Note that the reST is recommended by the PEP 287 And... Nowadays, the probably more prevalent format is the reStructuredText (reST) format In my experience, this is the case. More on reddit.com
🌐 r/learnpython
3
14
August 27, 2017
Which docstring format do you prefer?
There's also PEP 257 -- Docstring Conventions . More on reddit.com
🌐 r/learnpython
4
3
April 5, 2021
Docstrings for functions vs methods: what to do when a class property doesn't return anything but does modify class attributes?
IMO, if attribute access mutates the class or instance, it should be a method in most cases. Not all f(self) or f(cls) methods need to be properties. It's fine for a property to do some work to get it's value via @property, but if it's modifying state (especially if that is its only function), the fact that it is a method adds clarity that it does something. Also, I'm not 100% clear on what you're stating here, as you mention class properties and class attributes, but the normal @property decorator is for instance attributes, not class attributes. Of course those can still be modified by the instance, but is generally not the recommended way to do that. Can you clarify whether you mean class or instance attributes/properties? More on reddit.com
🌐 r/learnpython
8
1
December 13, 2018
🌐
DataCamp
datacamp.com › tutorial › docstrings-python
Python Docstrings Tutorial : Examples & Format for Pydoc, Numpy, Sphinx Doc Strings | DataCamp
February 14, 2025 - They are used to provide documentation for Python modules, classes, and methods, and are typically written in a specialized syntax called "reStructuredText" that is used to create formatted documentation. In Python, you can access a docstring using the __doc__ attribute of the object. For example, you could access the docstring for a function using my_function.__doc__or the docstring for a class using MyClass.__doc__.
🌐
AskPython
askpython.com › python › python-docstring
Python Docstring - AskPython
February 16, 2023 - Every Python script is also a module. We can define this module docstring as: """ This module shows some examples of Python Docstrings Classes: Employee Functions: multiply(a, b) """
🌐
GeeksforGeeks
geeksforgeeks.org › python › python-docstrings
Python Docstrings - GeeksforGeeks
September 19, 2025 - Example: This function multiplies two numbers using Google-style docstrings. ... def multiply(a, b): """ Multiply two numbers. Args: a (int): First number. b (int): Second number.
🌐
Readthedocs
sphinxcontrib-napoleon.readthedocs.io › en › latest › example_google.html
Example Google Style Python Docstrings — napoleon 0.7 documentation
Attributes: attr1 (str): Description of `attr1`. attr2 (:obj:`int`, optional): Description of `attr2`. """ def __init__(self, param1, param2, param3): """Example of docstring on the __init__ method. The __init__ method may be documented in either the class level docstring, or as a docstring ...
🌐
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 - In the above example the docstrings were used in both the class “iphone_entry”and the methods “check_id”, “signatures” inside the class. Docstrings can also be used to create libraries and they can also be used to get information of python libraries (modules) like in the example below.
🌐
Noirlab
datalab.noirlab.edu › docs › manual › DevGuide › DocumentingPythonAPIswithDocstrings › DocumentingPythonAPIswithDocstrings.html
3.2. Documenting Python APIs with Docstrings — Data Lab 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.
Find elsewhere
🌐
FavTutor
favtutor.com › blogs › docstring-python
Python Docstring: How to Write Docstrings? (with Examples)
June 6, 2023 - An example of a multi-line docstring is shown here: class Rectangle: """ This class represents a rectangle. Attributes: width (int): The width of the rectangle. height (int): The height of the rectangle.
🌐
Python Land
python.land › home › language deep dives › python docstring: documenting your code
Python Docstring: Documenting Your Code • Python Land Tutorial
May 10, 2022 - class MyDocumentedClass: """This class is well documented but doesn't do anything special.""" def do_nothing(self): """This method doesn't do anything but feel free to call it anyway.""" pass · As you can see, I created these strings with triple quotes. It’s for a reason: they are more recognizable as a docstring, and it’s easier to expand them to multi-line strings later on (if needed).
🌐
iO Flood
ioflood.com › blog › python-docstring
Python Docstring Usage Guide (With Examples)
December 11, 2023 - Now, let’s see an example where ... a class: class MathOperations: """ This is a class to perform basic mathematical operations. The class demonstrates the usage of docstrings in a python class. """ def __init__(self, num1, num2): """Constructor to initialize the attributes of the class....
🌐
Real Python
realpython.com › how-to-write-docstrings-in-python
How to Write Docstrings in Python – Real Python
August 25, 2025 - Python docstrings are string literals that show information regarding Python functions, classes, methods, and modules, allowing them to be properly documented. They are placed immediately after the definition line in triple double quotes ("""). Their use and convention are described in PEP 257, which is a Python Enhancement Proposal (PEP) that outlines conventions for writing docstrings. Docstrings don’t follow a strict formal style. Here’s an example:
🌐
Real Python
realpython.com › documenting-python-code
Documenting Python Code: A Complete Guide – Real Python
July 17, 2026 - Class method docstrings should contain the following: A brief description of what the method is and what it’s used for · Any arguments (both required and optional) that are passed including keyword arguments · Label any arguments that are considered optional or have a default value · Any side effects that occur when executing the method ... Let’s take a simple example of a data class that represents an Animal.
Top answer
1 of 2
11

Yes just drop the methods section from the class docstring. I've never ever seen something like that used.(It is used in few places in the standard library.)  The class docstring needs to just describe the class and the docstring of individual methods then handle describing themselves.

Also the wording in the PEP to me means that the class docstring "should" list the public methods, but not describe them in any other way.(This is also how the above standard library example does it.)  But as said, I would never even do that, since the code speaks for itself and that kind of listing is bound to get out-of-date.

Final note: I personally prefer to use the Google docstring style, because to me it's the clearest and cleanest.

2 of 2
2

example:

class Animal:
    """
    A class used to represent an Animal

    ...

Attributes
----------
says_str : str
    a formatted string to print out what the animal says
name : str
    the name of the animal
sound : str
    the sound that the animal makes
num_legs : int
    the number of legs the animal has (default 4)

Methods
-------
says(sound=None)
    Prints the animals name and what sound it makes
"""

says_str = "A {name} says {sound}"

def __init__(self, name, sound, num_legs=4):
    """
    Parameters
    ----------
    name : str
        The name of the animal
    sound : str
        The sound the animal makes
    num_legs : int, optional
        The number of legs the animal (default is 4)
    """

    self.name = name
    self.sound = sound
    self.num_legs = num_legs

def says(self, sound=None):
    """Prints what the animals name is and what sound it makes.

    If the argument `sound` isn't passed in, the default Animal
    sound is used.

    Parameters
    ----------
    sound : str, optional
        The sound the animal makes (default is None)

    Raises
    ------
    NotImplementedError
        If no sound is set for the animal or passed in as a
        parameter.
    """

    if self.sound is None and sound is None:
        raise NotImplementedError("Silent Animals are not supported!")

    out_sound = self.sound if sound is None else sound
    print(self.says_str.format(name=self.name, sound=out_sound))

Yep, listing methods in the class docstring, then each method again documented, according to this standard. I reccomend using sphinx, though: https://www.sphinx-doc.org/en/master/contents.html

🌐
Lsst
developer.lsst.io › v › DM-15183 › python › numpydoc.html
Documenting Python APIs with Docstrings — LSST DM Developer Guide DM-15183 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.
🌐
Mimo
mimo.org › glossary › python › docstrings
Python Docstrings: Syntax, Usage, and Examples
Go right after the definition line of a function, class, or module. Use triple quotes to enclose the text. ... Every function should have a docstring explaining its purpose, parameters, and return value. This is especially valuable for Python functions that accept args or keyword arguments (kwargs).
🌐
Tutorialspoint
tutorialspoint.com › python › python_docstrings.htm
Python - Docstrings
This attribute contains the ... In the following example, we are defining two functions, "add" and "multiply", each with a docstring describing their parameters and return values....
🌐
EDUCBA
educba.com › home › software development › software development tutorials › python tutorial › python docstring
Python Docstring | Complete Guide to Python Docstring
March 24, 2023 - Python Doctstring is the documentation string that occurs at class, method, module or function level. A docstring is simply a multi-line string that is not assigned to anything. It is specified in the source code that is used to document a specific segment of code.
Address: Unit no. 202, Jay Antariksh Bldg, Makwana Road, Marol, Andheri (East),, 400059, Mumbai
🌐
Pandas
pandas.pydata.org › docs › development › contributing_docstring.html
pandas docstring guide — pandas 3.0.6 documentation
Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num2 · Some standards regarding docstrings exist, which make them easier to read, and allow them be easily exported to other formats such as html or pdf. The first conventions every Python docstring should ...
🌐
Rutgers
iw3.math.rutgers.edu › solutions › example_google.html
Example Google Style Python Docstrings — Solutions 0.0.1 documentation
Docstring after attribute, with type specified. ... Class methods are similar to regular functions. ... Do not include the self parameter in the Args section. ... True if successful, False otherwise. ... list of str: Properties with both a getter and setter should only be documented in their getter method. If the setter method contains notable behavior, it should be mentioned here. exception example_google.ExampleError(msg, code)[source]