Skip to content
Sarj Sarj Sarj Standards

docstring-returns-restate-signature

Google-style Returns and Yields documentation must add facts beyond the corresponding annotated result type.

SARJ087 Rule source Tests Catalog JSON

Why

Repeating a result type or callable name adds noise and can drift without explaining identity, polarity, cardinality, ordering, ownership, or empty-result behavior.

Fix

Remove only the redundant Returns or Yields section. Keep identity, ownership, units, ordering, shape, laziness, sentinel values, and success conditions in the public docstring.

Examples

Before — flagged Return description repeats the signature
app/lines.py
def get_line_length(line: list[str]) -> int:
    """Measure a rendered line.


    Returns:
        The line length.
    """
    return len(line)
After — preferred Return description records semantics
app/lines.py
def get_line_length(line: list[str]) -> int:
    """Measure a rendered line.


    Returns:
        The number of render fragments queued for output.
    """
    return len(line)