跳到内容

docstring 中包含签名 (D402)

源自 pydocstyle 代码检查器。

作用

检查函数 docstring 的摘要行是否包含函数签名。

为什么这不好？

PEP 257 建议不要在 docstring 中包含函数签名。相反，可以考虑使用类型注解作为函数参数和返回值的文档形式。

此规则可能不适用于所有项目；其适用性是一个惯例问题。 默认情况下，在使用 google 和 pep257 约定启用此规则，而在使用 numpy 约定禁用此规则。

示例

def foo(a, b):
    """foo(a: int, b: int) -> list[int]"""

建议改为

def foo(a: int, b: int) -> list[int]:
    """Return a list of a and b."""

Options (选项)

参考