Python · maintainability

no-typed-doc-sections

python:no-typed-doc-sections

Docstring sections must not repeat types already present in a fully typed signature.

Code: SARJ092
Default: error
Fix: none
Languages: python

Why

Duplicated type spellings drift from annotations and add noise without strengthening the behavioral contract.

Fix

Remove the repeated type while retaining behavioral facts, constraints, units, and error conditions.

Before / after

Executed by this rule’s unit tests.

Before

Parameter type repeats the annotation

app.py · focus

def decode(value: str) -> dict[str, object]:
    """Decode the value.

    Args:
        value (str): Text to decode.
    """
    return {}

After

Argument section records behavior

publisher.py · focus

def publish(message: str, *, retry: bool) -> None:
    """Publish one message.

    Args:
        message: Wire payload retained for the audit record.
        retry: Whether a prior partial write may be attempted again.
    """

Limits

Only fully typed functions are checked, and a documented type must match the signature before it is reported.
Runtime-consumed prompt, CLI, and route docstrings and untyped or partially typed signatures are excluded.