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.

Answer from ruohola on Stack Overflow
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

🌐
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 ...
🌐
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.
🌐
Sphinx
sphinx-doc.org › en › master › usage › extensions › example_google.html
Example Google Style Python Docstrings — Sphinx documentation
Args: msg (str): Human readable string describing the exception. code (:obj:`int`, optional): Error code. Attributes: msg (str): Human readable string describing the exception. code (int): Exception error code. """ def __init__(self, msg, code): self.msg = msg self.code = code class ExampleClass: """The summary line for a class docstring should fit on one line.
🌐
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 ...
🌐
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.
🌐
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.
🌐
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]
Find elsewhere
🌐
Code with Mosh
forum.codewithmosh.com › python
Hi, I'm a beginner to python. as I'm running my program it works perfectly but I can see a message in problem saying that missing module docstring pylint(missing-module-docstring). can someone help me to fix this bug - Python - Code with Mosh Forum
Hi! Actually its not a big deal. Docstrings are just for documentation (in Your example - for documenting the content of a module or file). You can just add docstring on top of the file: · I am a beginner too. I spent a lot of hours figuring this out. Follow my instruction below · You need ...
Published: November 2, 2021
🌐
GitHub
github.com › Akuli › python-tutorial › blob › master › basics › docstrings.md
python-tutorial/basics/docstrings.md at master · Akuli/python-tutorial
Here are some examples of popular docstring styles to choose from: Sphinx is the Python documentation tool that the official Python documentation uses. By default, sphinx expects you to write docstrings like this: class Vehicles: """ The Vehicles object contains lots of vehicles.
Author: Akuli
🌐
Readthedocs
gemseo.readthedocs.io › en › stable › software › example_google_docstring.html
Example Google Style Docstrings — GEMSEO 6.3.3 documentation
Args: n: The upper limit of the range to generate, from 0 to `n` - 1. Yields: The next number in the range of 0 to `n` - 1. Examples: Examples should be written in doctest format, and should illustrate how to use the function. >>> print([i for i in example_generator(4)]) [0, 1, 2, 3] """ yield from range(n) class ExampleClass: """The summary line for a class docstring should fit on one line.
🌐
Python Tutorial
pythontutorial.net › home › python basics › python function docstrings
Python Function Docstrings
March 26, 2025 - Python stores the docstrings in the __doc__ property of the function. The following example shows how to access the __doc__ property of the add() function:
🌐
Linux Hint
linuxhint.com › python-docstring
Python docstring – Linux Hint
The way of declaring and accessing ... list and reverse the data of the list. A numeric list of 8 elements has been declared in the class, and the docstring has been defined at the beginning of the class by using triple single quotes....
🌐
Software Testing Help
softwaretestinghelp.com › home › python › python docstring: documenting and introspecting functions
Python Docstring: Documenting And Introspecting Functions
April 1, 2025 - The good news is that its information can be used to implement type checks. This is commonly done in Python decorators. ... Answer: A docstring is the first string literal enclosed in triple-double quotes (“””), and immediately follows a class, module, or function’s definition.
🌐
Readthedocs
sphinxcontrib-napoleon.readthedocs.io › en › latest › example_numpy.html
Example NumPy 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 on the __init__ method itself.
🌐
Hektor Profe
hektorprofe.github.io › python › documentacion-y-pruebas › docstrings
Docstrings | Curso de Python | Hektor Profe
October 6, 2018 - def hola(arg): """Este es el docstring de la función""" print("Hola", arg, "!") hola("Héctor") Hola Héctor ! Para consultar la documentación es tan sencillo como utilizar la función reservada help y pasarle el objeto: ... De la misma forma podemos establecer la documentación de la clase ...
🌐
Noao
datalab.noao.edu › docs › manual › DevGuide › styleguide › numpydoc.html
3.3. Documenting Python APIs with Docstrings — Data Lab 1.1.1 documentation
December 11, 2020 - 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.
🌐
Sam et Max
sametmax.com › les-docstrings
Les docstrings en Python – Sam & Max
November 29, 2016 - Sur les docstrings très longues (il n’est pas rare qu’une docstring soit plus longue que le code qu’elle documente), comme celles des modules, on peut sous-ligner les titres et sous-titres avec des = et des -. ... #!/usr/bin/env python # -*- coding: utf-8 -*- """ The ``obvious`` module ====================== Use it to import very obvious functions. :Example: >>> from obvious import add >>> add(1, 1) 2 This is a subtitle ------------------- You can say so many things here !
🌐
Python
docs.python.org › 3 › library › doctest.html
doctest — Test interactive Python examples
If M.__test__ exists, it must be a dict, and each entry maps a (string) name to a function object, class object, or string. Function and class object docstrings found from M.__test__ are searched, and strings are treated as if they were docstrings. In output, a key K in M.__test__ appears with name M.__test__.K. For example, place this block of code at the top of example.py:
🌐
Codegrepper
codegrepper.com › code-examples › python › docstrings+in+python
docstrings in python Code Example
January 19, 2021 - # Docstrings are used create your own Documentation for a function or for a class # we are going to write a function that akes a name and returns it as a title. def titled_name(name): # the following sting is Docstring """This function takes name and returns it in a title case or in other words it will make every first letter of a word Capitalized""" return f"{name}".title()