`missing-returns`¶

Part of: Enrichment Check


Check	enrichment
Category	required
Applies to	functions, methods
Since	v1.13.0

Function returns a value but has no Returns section

What it detects¶

This rule flags functions and methods that contain return <expr> statements in their body but have no Returns: section in their docstring. Bare return and return None are treated as control-flow idioms and do not trigger this rule.

Why is this a problem?¶

Callers of the function don't know what to expect back. Without a documented Returns: section, downstream code can't correctly handle the return value, and API documentation generated by mkdocstrings will lack return type information.

How to Fix¶

Add a Returns: section describing the type and meaning of the return value:

Returns:
    The parsed configuration as a dictionary.

For functions with multiple return types, describe each possibility:

Returns:
    The matched user, or ``None`` if no match is found.

Example¶

ViolationFix

def find_user(user_id: int) -> User | None:
    """Look up a user by ID.

    Args:
        user_id: The user's numeric identifier.
    """
    return db.query(User).get(user_id)

def find_user(user_id: int) -> User | None:
    """Look up a user by ID.

    Args:
        user_id: The user's numeric identifier.

    Returns:
        The matched user, or ``None`` if no match is found.
    """
    return db.query(User).get(user_id)

Exceptions¶

This rule is automatically skipped for:

Dunder methods (__init__, __repr__, __len__, etc.)
@property and @cached_property methods
@abstractmethod methods (interface contracts)
@overload signatures
Stub functions (body is pass, ..., or raise NotImplementedError)

missing-returns¶