docstring-missing-yields (DOC402)

Derived from the pydoclint linter.

This rule is unstable and in preview. The --preview flag is required for use.

What it does

Checks for functions with yield statements missing a "yields" section in their docstring.

Why is this bad?

Docstrings missing yields sections are a sign of incomplete documentation or refactors.

This rule is not enforced for abstract methods, stubs functions, or functions that only yield None.

Example

def count_to_n(n: int) -> int:
    """Generate integers up to *n*.

    Args:
        n: The number at which to stop counting.
    """
    for i in range(1, n + 1):
        yield i

Use instead:

def count_to_n(n: int) -> int:
    """Generate integers up to *n*.

    Args:
        n: The number at which to stop counting.

    Yields:
        int: The number we're at in the count.
    """
    for i in range(1, n + 1):
        yield i