Skip to content

extra-returns-in-docstring

Part of: Enrichment Check
Check enrichment
Category recommended
Applies to functions, methods
Since v1.16.0

Docstring has a Returns section but the function does not return a value

What it detects

This rule flags functions and methods that have a Returns: section but no meaningful return value in their body. Bare return and return None are control-flow idioms, not meaningful returns — they do not satisfy the check.

Why is this a problem?

A Returns: section on a function that never returns a value misleads callers into expecting and using a return value. After a refactor that removes the return path, a leftover Returns: section creates confusion and may cause None-related bugs in calling code.

How to Fix

Remove the Returns: section if the function has no meaningful return value:

def save(data: dict) -> None:
    """Save data to disk."""

If the function should return a value, add the return statement.

Example

def save(data: dict) -> None:
    """Save data to disk.

    Returns:
        The saved file path.
    """
    with open("data.json", "w") as f:
        json.dump(data, f)

def save(data: dict) -> None:
    """Save data to disk."""
    with open("data.json", "w") as f:
        json.dump(data, f)

Configuration

This rule is controlled by check-extra-returns (default: true). The forward check (missing-returns) is controlled independently by require-returns.

[tool.docvet.enrichment]
check-extra-returns = false

Exceptions

This rule is automatically skipped when:

  • The function is @abstractmethod (interface contract documentation)
  • The function body is a stub (pass, ..., or raise NotImplementedError)
  • The symbol is a class, module, or other non-function type
  • The docstring has no Returns: section