yield-missing-description (PDF708)¶

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 that parsed yield entries in owning function docstrings include a prose description.

Only functions that actually contain yield expressions are checked. Stub and abstract functions are skipped.

Why is this useful?¶

Yield documentation should explain the meaning of generated values.

Ruff compatibility¶

None.

Examples¶

PDF708 reports yield entries without descriptions:

docstring-convention = "google"

def function() -> Iterator[int]:
    """Yield values.

    Yields:
        int:
    """
    yield 1

PDF708: Line 5: Function yield 'yield' docstring entry is missing a description

Yield entries with descriptions are accepted:

docstring-convention = "google"

def function() -> Iterator[int]:
    """Yield values.

    Yields:
        int: Next value.
    """
    yield 1

Non-generator functions are not checked by yield-entry rules:

docstring-convention = "google"

def function() -> int:
    """Return a value.

    Yields:
        int:
    """
    return 1

Options¶

None.