Learn How to Write Multi-line Documentation in Python: Absolute Beginners Tutorial

When a Python function grows beyond a few lines, a short comment above the def line is not enough to explain what it does, what it accepts, and what it returns. Python solves this with docstrings -- string literals placed directly inside a definition that the interpreter stores, that the built-in help() function displays, and that documentation generators like Sphinx can turn into full reference pages. This tutorial walks you through multi-line docstrings from first principles so you can start writing clear, useful documentation in your own code today.

If you have ever opened someone else's Python project and immediately understood what each function did without reading through the implementation, you were reading good docstrings. If you have ever stared at a function signature for minutes trying to figure out what the parameters expected, you were looking at code that lacked them. Multi-line docstrings sit at the heart of this difference, and Python gives them first-class treatment that no other common language matches quite as directly.

What Is a Docstring and Why Does It Matter?

A docstring is a string literal that appears as the very first statement inside a module, function, class, or method definition. Python's interpreter recognizes that placement and automatically assigns the string to the object's __doc__ attribute. That single rule is what separates a docstring from every other string or comment in your code.

Regular comments begin with the # character and are stripped out during compilation. They exist only in the source file. A docstring, on the other hand, is preserved at runtime. You can print it, pass it to help(), and hand it off to documentation generation tools. This means the documentation lives with the code and travels wherever the code goes.

def calculate_area(radius):
    """Calculate the area of a circle given its radius."""
    import math
    return math.pi * radius ** 2

# Access the docstring at runtime
print(calculate_area.__doc__)
# Output: Calculate the area of a circle given its radius.

help(calculate_area)
# Displays the docstring in an interactive viewer

The example above uses a one-line docstring because the explanation fits on a single line. That works when the function is simple. When a function accepts multiple parameters, raises exceptions, or returns complex data, a single sentence is not enough. That is where multi-line docstrings come in.

The distinction between a comment and a docstring matters for beginners because it affects how you think about documentation. Comments explain why code works the way it does. Docstrings explain what code does and how to use it. Both are valuable, and they serve different audiences.

# This is WRONG -- the docstring is not the first statement
def bad_example(x):
    result = x * 2
    """Multiply x by two."""   # Python ignores this as a docstring
    return result

print(bad_example.__doc__)
# Output: None

Anatomy of a Multi-line Docstring

A multi-line docstring has a specific structure defined by PEP 257. It begins with a summary line on the same line as the opening triple quotes. That summary should fit on one line and describe what the function does in a concise sentence. After the summary comes a blank line, followed by a more detailed description. The closing triple quotes go on a line by themselves.

def connect_to_database(host, port, timeout=30):
    """Establish a connection to the specified database server.

    Attempts to connect using TCP on the given host and port.
    If the connection is not established within the timeout
    period, a ConnectionError is raised.

    Args:
        host (str): The hostname or IP address of the server.
        port (int): The port number to connect on.
        timeout (int): Seconds to wait before giving up.
            Defaults to 30.

    Returns:
        Connection: An active database connection object.

    Raises:
        ConnectionError: If the server cannot be reached
            within the timeout period.
    """
    # implementation here
    pass

Every part of that structure serves a purpose. The summary line on the first line allows automatic indexing tools to extract a short description without parsing the entire docstring. The blank line signals to parsers that the summary is complete. The extended description provides the detail that a developer needs when the summary alone is not enough.

PEP 257 also requires that the indentation of every line in the docstring matches the indentation of the opening quotes. Documentation tools strip a uniform amount of leading whitespace from the second and subsequent lines, using the minimum indentation of all non-blank lines after the first line as the baseline.

Where Docstrings Belong

You can place docstrings in four locations: modules (at the very top of a .py file), classes (directly after the class line), functions (directly after the def line), and methods (same as functions, but inside a class). Each location has slightly different conventions for what to include.

"""File utilities for reading and writing CSV data.

This module provides helper functions for loading CSV files
into Python data structures and writing them back to disk.

Functions:
    read_csv -- Load a CSV file and return a list of dicts.
    write_csv -- Write a list of dicts to a CSV file.
"""

import csv


class DataLoader:
    """Load and validate structured data from external sources.

    Supports CSV and JSON input formats. Each instance is bound
    to a single source file specified at construction time.

    Attributes:
        filepath (str): Path to the source file.
        encoding (str): Character encoding used when reading.
    """

    def __init__(self, filepath, encoding="utf-8"):
        """Initialize the DataLoader with a file path.

        Args:
            filepath (str): Path to the data file.
            encoding (str): File encoding. Defaults to utf-8.
        """
        self.filepath = filepath
        self.encoding = encoding

Three Popular Docstring Formatting Styles

PEP 257 defines the structural rules for docstrings -- where they go, how to separate the summary from the body -- but it does not prescribe how to format parameter lists, return values, or exception documentation within the body. Three community conventions have emerged to fill that gap, and each has its own strengths.

reStructuredText (reST) Style

This is the native format for Sphinx, the documentation generator used by the Python standard library and many open-source projects. It uses field-list directives like :param:, :type:, :returns:, and :raises:. PyCharm generates reST-style stubs by default when you type triple quotes after a def line and press Enter.

def send_email(recipient, subject, body):
    """Send an email message to a single recipient.

    Connects to the configured SMTP server and delivers
    the message. The connection is closed automatically
    after delivery.

    :param recipient: Email address of the recipient.
    :type recipient: str
    :param subject: Subject line of the email.
    :type subject: str
    :param body: Plain-text body content.
    :type body: str
    :returns: True if the email was accepted by the server.
    :rtype: bool
    :raises smtplib.SMTPException: If delivery fails.
    """
    pass

Google Style

Google style uses plain section headers followed by indented content. It tends to be the most readable in source code, especially for shorter docstrings. Sphinx can parse it through the sphinx.ext.napoleon extension.

def send_email(recipient, subject, body):
    """Send an email message to a single recipient.

    Connects to the configured SMTP server and delivers
    the message. The connection is closed automatically
    after delivery.

    Args:
        recipient (str): Email address of the recipient.
        subject (str): Subject line of the email.
        body (str): Plain-text body content.

    Returns:
        bool: True if the email was accepted by the server.

    Raises:
        smtplib.SMTPException: If delivery fails.
    """
    pass

NumPy Style

NumPy style uses section headers underlined with dashes. It requires more vertical space but is easier to scan when docstrings contain long parameter descriptions. Libraries like NumPy, pandas, and SciPy follow this convention, and Sphinx supports it through the same napoleon extension.

def send_email(recipient, subject, body):
    """Send an email message to a single recipient.

    Connects to the configured SMTP server and delivers
    the message. The connection is closed automatically
    after delivery.

    Parameters
    ----------
    recipient : str
        Email address of the recipient.
    subject : str
        Subject line of the email.
    body : str
        Plain-text body content.

    Returns
    -------
    bool
        True if the email was accepted by the server.

    Raises
    ------
    smtplib.SMTPException
        If delivery fails.
    """
    pass

"A universal convention supplies all of maintainability, clarity, consistency." — PEP 257, Python Software Foundation

Python Learning Summary Points

1. A docstring is a string literal placed as the first statement inside a module, class, function, or method. Python stores it in the __doc__ attribute and makes it available to help() and documentation generators.
2. Multi-line docstrings follow a specific PEP 257 structure: a one-line summary, a blank line, then a detailed description, with the closing triple quotes on their own line.
3. Three formatting styles are widely used for structuring parameter and return documentation: reStructuredText (Sphinx native), Google style (concise and readable), and NumPy style (common in scientific libraries). Consistency within a project matters more than which style you choose.
4. The most common beginner mistake is placing code before the docstring, which causes Python to treat the string as an ordinary expression rather than documentation. Always make the docstring the very first statement.
5. Use help() and __doc__ to verify your docstrings at runtime. If the output is None, the string is not in the correct position.

Writing thorough multi-line docstrings takes a few extra seconds per function, but the payoff compounds every time someone (including your future self) needs to understand what a piece of code does without reading through the implementation. Start with simple functions, pick a formatting style, and build the habit early. Your codebase will be better for it.