docstring-missing-yields (DOC402)

源自 pydoclint 代码检查器。

此规则不稳定且处于预览状态。使用需要 --preview 标志。

作用

检查包含 yield 语句，但在文档字符串中缺少 “Yields” 部分的函数。

为什么这不好？

缺少 “Yields” 部分表明文档不完整。

此规则不适用于抽象方法或仅 yield None 的函数。它也会忽略 “stub functions”（存根函数）：函数体仅由 pass、...、raise NotImplementedError 或类似内容组成。

示例

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

建议改为

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