Skip to content

missing-return-documentation (PDF502)

Added in 1.0.0 Never fix Convention

Part of the PDF rule category.

View source · View documentation source · Search issues

Fix is not available.

Rule is disabled if docstring-convention is none or pep257.

What it does

Checks function and method docstrings for missing return-value documentation when the function body has a meaningful return value.

A meaningful return is return <expr> where <expr> is not None. Bare return, return None, any generator function, functions without docstrings, abstract methods, and stub functions are ignored. A function is a generator for this rule if it contains any top-level yield, including bare yield and yield None. Nested functions, classes, and lambdas are ignored by the enclosing function and checked independently when they have their own docstrings.

Return documentation is present when the active docstring parser finds a non-empty Google return section, NumPy return section, or reST return field. In Google return sections, bare None and None. entries are treated like None: entries.

By default, this rule reports missing return documentation only when the docstring already has recognized return documentation, such as an empty return section. Broader shared missing-documentation modes can require return documentation for public docstrings with body content, or for all public docstrings.

Why is this useful?

Return documentation explains the meaning of values that cannot always be inferred from annotations alone.

Ruff compatibility

This rule replaces Ruff's DOC201. It follows the same broad intent, while using pydocformatter's configured docstring parser and without Ruff's pydoclint-specific one-line-docstring or property-decorator options.

Examples

This function returns a meaningful value without documenting it:

docstring-convention = "google"
docstring-missing-documentation = "all-docstrings"

def calculate(value):
    """Calculate a value."""
    return value + 1

PDF502: Line 3: Function return value is missing docstring documentation

The rule reports the first meaningful return in each checked function. Bare return, return None, and generator stop values are not ordinary return-value documentation targets:

docstring-convention = "google"
docstring-missing-documentation = "all-docstrings"

def value(flag):
    """Return a value."""
    if flag == "skip":
        return
    if flag == "empty":
        return None
    return flag


def generator():
    """Generate values."""
    yield 1
    return 2


def empty_generator():
    """Generate no values."""
    yield None
    return 3

PDF502: Line 7: Function return value is missing docstring documentation

Recognized return documentation satisfies the rule. Google sections, reST fields, and NumPy sections are all valid when the matching convention is active:

docstring-convention = "google"

def google_value():
    """Return a value.

    Returns:
        int: The value.
    """
    return 1


def none_value():
    """Return a value.

    Returns:
        None.
    """
    return 2

docstring-convention = "rest"

def rest_value():
    """Return a value.

    :rtype: int
    """
    return 1

docstring-convention = "numpy"

def numpy_value():
    """Return a value.

    Returns
    -------
    int
        The value.
    """
    return 1

The active convention controls which documentation is recognized. Under none and pep257, this rule is disabled even when selected explicitly:

docstring-convention = "none"
docstring-missing-documentation = "all-docstrings"

def value():
    """Return a value.

    :returns: The value.
    """
    return 1

Options