跳到内容

未文档化参数 (D417)

源自 pydocstyle 代码检查器。

作用

检查函数文档字符串是否包含函数中所有参数的文档。

为什么这不好？

此规则有助于防止您留下未完成或不完整的 Google 风格文档字符串。多行 Google 风格文档字符串应描述它们所记录的函数的所有参数。

多行文档字符串通常由摘要行、空行以及一系列部分组成，每个部分都有一个节头和一个节体。函数文档字符串通常包含函数参数的部分；此规则仅关注该部分。请注意，此规则仅检查带有参数（例如，Args）部分的文档字符串。

使用 google 约定启用此规则，使用 pep257 和 numpy 约定禁用此规则。

示例

def calculate_speed(distance: float, time: float) -> float:
    """Calculate speed as distance divided by time.

    Args:
        distance: Distance traveled.

    Returns:
        Speed as distance divided by time.

    Raises:
        FasterThanLightError: If speed is greater than the speed of light.
    """
    try:
        return distance / time
    except ZeroDivisionError as exc:
        raise FasterThanLightError from exc

建议改为

def calculate_speed(distance: float, time: float) -> float:
    """Calculate speed as distance divided by time.

    Args:
        distance: Distance traveled.
        time: Time spent traveling.

    Returns:
        Speed as distance divided by time.

    Raises:
        FasterThanLightError: If speed is greater than the speed of light.
    """
    try:
        return distance / time
    except ZeroDivisionError as exc:
        raise FasterThanLightError from exc

Options (选项)

参考