From the Sphinx documentation:

returns, return: Description of the return value.
rtype: Return type. Creates a link if possible.

You might also benefit from:

raises, raise, except, exception: That (and when) a specific exception is raised.

So, as one example:

def get_previous_release(release_id):
    """ 
    Holt Vorgängeritem eines Items mit der ID release_id

    :param release_id: ID des items für das Release
    :type release_id: int
    :returns: appropriate release object
    :rtype: AlphaRelease, BetaRelease, or VRelease
    :raises ValueError: if release_id not an int
    :raises LookupError: if given release_id not found
    :raises TypeError: if id doesn't reference release
    """
    ... # your code here

Unfortunately there is not a strict or canonical choice in the Sphinx grammar and vocabulary for multiple return types. Often one would state a super-type of all the types that might be returned, if one existed (GenericRelease e.g.). But Python is just now, in its mid- to late-Python 3 era, defining a richer type notation. The typing module defines an evolving new grammar for such types independent of the old Sphinx definitions. If you wished to use this emerging standard, you might try something like:

:rtype: Union[AlphaRelease, BetaRelease, VRelease]
Answer from Jonathan Eunice on Stack Overflow
Top answer
1 of 2
45

From the Sphinx documentation:

returns, return: Description of the return value.
rtype: Return type. Creates a link if possible.

You might also benefit from:

raises, raise, except, exception: That (and when) a specific exception is raised.

So, as one example:

def get_previous_release(release_id):
    """ 
    Holt Vorgängeritem eines Items mit der ID release_id

    :param release_id: ID des items für das Release
    :type release_id: int
    :returns: appropriate release object
    :rtype: AlphaRelease, BetaRelease, or VRelease
    :raises ValueError: if release_id not an int
    :raises LookupError: if given release_id not found
    :raises TypeError: if id doesn't reference release
    """
    ... # your code here

Unfortunately there is not a strict or canonical choice in the Sphinx grammar and vocabulary for multiple return types. Often one would state a super-type of all the types that might be returned, if one existed (GenericRelease e.g.). But Python is just now, in its mid- to late-Python 3 era, defining a richer type notation. The typing module defines an evolving new grammar for such types independent of the old Sphinx definitions. If you wished to use this emerging standard, you might try something like:

:rtype: Union[AlphaRelease, BetaRelease, VRelease]
2 of 2
1

Python 3.10 | (pipe, binary or) Union type hint syntax sugar

This is going to be the way forward in the future, so clean:

def f(i: int | str) -> int | str:
    if type(i) is str:
        return int(i) + 1
    else:
        return str(i)

Also is also already fully supported by Sphinx:

More details at: How to express multiple types for a single parameter or a return value in docstrings that are processed by Sphinx?

🌐
DataCamp
datacamp.com › tutorial › docstrings-python
Python Docstrings Tutorial : Examples & Format for Pydoc, Numpy, Sphinx Doc Strings | DataCamp
February 14, 2025 - #Returns: # reverse(str1):The string which gets reversed. reverse_str1 = '' i = len(str1) while i > 0: reverse_str1 += str1[i - 1] i = i- 1 return reverse_str1 ... There are a couple of ways of writing or using a Docstring, i.e., one-line docstring and multi-line docstring. Let's learn them one by one. One-line docstrings are short descriptions that fit on a single line. They are enclosed in triple quotes (''' or """), and the closing quotes must be on the same line. Although both triple-single and triple-double quotes work, the standard convention in Python is to use triple-double quotes (""").
Discussions

Properly documenting the return type in the "Returns" section when using google docstring style
Hi, I noticed that when using the google parser for docstrings, it is not possible to properly document the return type of the return value within the Returns section itself without using type anno... More on github.com
🌐 github.com
6
March 15, 2023
coding standards - Python method docstring: to use or not to use Args: Returns: - Software Engineering Stack Exchange
0 Is it appropriate to use docstring `return` and `args` sections to specify HTTP statuses and URL parameters? 32 How to name a method which may or may not perform an action depending on a condition? 1 Python - Paradigm to compute different formulas with the same function More on softwareengineering.stackexchange.com
🌐 softwareengineering.stackexchange.com
March 6, 2019
python docstring for conditional return - Stack Overflow
What is the convention for writing a docstring for a function that conditionally either returns something or a NoneType? I see posts that might relate to this using Sphinx but I would like to know ... More on stackoverflow.com
🌐 stackoverflow.com
python - Is it appropriate to use docstring `return` and `args` sections to specify HTTP statuses and URL parameters? - Software Engineering Stack Exchange
I'm working on a web application project which uses Tornado as the web frontend. Currently, I'm in the process of writing up docs and adding docstrings to the code base with Pydoc. As a web API More on softwareengineering.stackexchange.com
🌐 softwareengineering.stackexchange.com
February 7, 2017
🌐
Python
peps.python.org › pep-0257
PEP 257 – Docstring Conventions | peps.python.org
There are two forms of docstrings: one-liners and multi-line docstrings. One-liners are for really obvious cases. They should really fit on one line. For example: def kos_root(): """Return the pathname of the KOS root directory.""" global _kos_root if _kos_root: return _kos_root ...
🌐
GitHub
github.com › mkdocstrings › griffe › issues › 137
Properly documenting the return type in the "Returns" section when using google docstring style · Issue #137 · mkdocstrings/griffe
March 15, 2023 - I noticed that when using the google parser for docstrings, it is not possible to properly document the return type of the return value within the Returns section itself without using type annotations or giving the value an explicit name.
Author: mkdocstrings
🌐
Python-sprints
python-sprints.github.io › pandas › guide › pandas_docstring.html
pandas docstring guide — Python documentation
Parameters ---------- num1 : int First number to add num2 : int Second number to add Returns ------- int The sum of `num1` and `num2` See Also -------- subtract : Subtract one integer from another Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num2 · Some standards exist about docstrings, so they are easier to read, and they can be exported to other formats such as html or pdf. The first conventions every Python docstring should follow are defined in PEP-257.
🌐
GeeksforGeeks
geeksforgeeks.org › python › python-docstrings
Python Docstrings - GeeksforGeeks
September 19, 2025 - # This is a comment (ignored by Python) name = "Daniel" # A string assigned to a variable def greet(): """This is a docstring. It explains what greet() does.""" return "Hello!"
🌐
JetBrains
jetbrains.com › help › pycharm › using-docstrings-to-specify-types.html
Specify types with docstrings | PyCharm Documentation
September 1, 2025 - PyCharm will generate a :return: and :rtype: section (or their equivalent in the selected docstring format).
Find elsewhere
Top answer
1 of 2
1

Writing good documentation is an art unto itself. Repeating yourself (e.g., repeating the variable name without underscores) is valueless; e.g., ++i; // increment i. If you're just repeating variable names without underscores, then you're not adding to anyone's understanding of the code.

I think it's always important to document what exceptions your methods throw. Return values aren't always as obvious as the original programmer thinks they are, so that's usually useful to document as well. (Again, if your method is get_foo(), saying "returns a foo" doesn't add anything.)

One thing to point out about that mypy example, the authors are using type hints which replaces a lot of what would be included in a docstring:

def warn(self, msg: str, context: Context, file: Optional[str] = None,
             origin: Optional[Context] = None)

Just from this, I know exactly what this method expects. Without it:

def warn(self, msg, context, file = None, origin = None)

I know a lot less.

2 of 2
3

I can not give you a definite answer, since such documentation also is sort of work and as such should be done, if useful. Generally speaking, only useful functionality should be exposed to the user and the application should be easy to use and understand.

Arguments Even obvious things can be exported for fast lookup. This is usually helpful for long and tedious methods. Optional parameters can be easily integrated by default parameters.
Return values With python it can be a pain to look up return values by inspecting objects (without source code), so when the source code is not at hand this should be done.
Side effects This is a quite vague term, but at least thread-safety support should be annotated in mixed applications cases (or explicitely). Default however is not thread-safe.
Exceptions Enforcing programmer/user input should be definitely documented, since this will cause crashing behavior.

In a small project, and as such internal project, for given knowledge and (hopefully) code, it does not make too much sense to comment everything. Concentrate on data structures and use cases for functions.

🌐
Google
google.github.io › styleguide › pyguide.html
Google Python Style Guide
If the function only returns None, this section is not required. It may also be omitted if the docstring starts with “Return”, “Returns”, “Yield”, or “Yields” (e.g. """Returns row from Bigtable as a tuple of strings.""") and the opening sentence is sufficient to describe the return value.
🌐
Stack Overflow
stackoverflow.com › questions › 64068306 › python-docstring-for-conditional-return
python docstring for conditional return - Stack Overflow
The docstring for a function or method should summarize its behavior and document its arguments, return value(s), side effects, exceptions raised, and restrictions on when it can be called (all if applicable).
🌐
Qiita
qiita.com › python
docstringのstyle3種の例 #Python - Qiita
April 18, 2019 - 案件で様々なstyleのdocstringを書いていると、つい混ざってしまうため自分の整理用にまとめます。 · def func(arg1, arg2, arg3): """Hello, func Lorem ipsum dolor sit amet, :param string arg1: First argument :param arg2: Second argument :type args2: list[int] :param arg3: Third argument :type args3: dict[str, int] :return: Return value :rtype: str or None :raises ValueError: if arg1 is empty string.
🌐
Note.nkmk.me
note.nkmk.me › home › python
Python Docstring Formats (Styles) and Examples | note.nkmk.me
August 26, 2023 - For example, PyCharm, an integrated development environment for Python, supports all three styles. Specify types with docstrings | PyCharm Documentation ... def func_rest(param1, param2): """Summary line. :param param1: Description of param1 :type param1: int :param param2: Description of param2 :type param2: str :returns: Description of return value :rtype: bool """ return True
🌐
iO Flood
ioflood.com › blog › python-docstring
Python Docstring Usage Guide (With Examples)
December 11, 2023 - Doctest searches your Docstrings for interactive Python sessions and runs these sessions to verify their functionality. This allows you to write tests for your code directly in your Docstrings, bolstering the assurance that your code performs as intended. def add(a, b): """Return the sum of a and b.
🌐
Pyansys
dev.docs.pyansys.com › doc-style › docstrings.html
Numpydoc docstrings — PyAnsys developer's guide
.. warning:: Use the ``warning`` directive within the docstring for any warnings that need to be explicitly stated. For example, you want to include a warning for a method that is to be deprecated in the next release. Parameters ---------- arg1 : int Description of ``arg1``. arg2 : str Description of ``arg2``. Returns ------- bool Description of the return value.
🌐
FavTutor
favtutor.com › blogs › docstring-python
Python Docstring: How to Write Docstrings? (with Examples)
June 6, 2023 - """ return a * b ... class Person: """ This class represents a person. Attributes: name (str): The person's name. age (int): The person's age. """ def __init__(self, name, age): self.name = name self.age = age · Triple quotes are used for writing docstrings in Python.
🌐
Python
docs.python.org › 3 › library › doctest.html
doctest — Test interactive Python examples
Only docstrings attached to objects belonging to module m are searched. Return (failure_count, test_count).
🌐
Better Programming
betterprogramming.pub › how-to-write-proper-docstrings-for-a-python-function-7c40b8d2e153
How to Write Proper Docstrings for a Python Function | by Yong Cui | Better Programming
February 2, 2022 - This is guaranteed to be unique among simultaneously existing objects. (CPython uses the object's memory address.) In Python, we can use the help function to retrieve the docstrings for the id function.
🌐
Softwareheritage
docs.softwareheritage.org › devel › contributing › sphinx.html
Sphinx gotchas — Software Heritage documentation
In Returns section you need to use “:” carefully as, if present, it will be interpreted as a separator between return type and description.
🌐
Codegrepper
codegrepper.com › code-examples › python › docstring+return+python
docstring return python Code Example
# 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()