跳到内容

undocumented-public-method (D102)

添加于 v0.0.70 · 相关问题 · 查看源码

源自 pydocstyle 代码检查器。

作用

检查未记录的公共方法定义。

为什么这不好？

公共方法应通过文档字符串（docstring）进行记录，以概述其目的和行为。

通常，方法文档字符串应描述该方法的行为、参数、副作用、异常、返回值以及任何其他对用户可能有用的信息。

如果代码库对方法文档字符串遵循特定标准格式，请遵循该格式以保持一致性。

本规则豁免了装饰有 @typing.override 的方法，因为在超类上记录方法而在子类的覆盖方法中不重复记录是一种常见做法。

示例

class Cat(Animal):
    def greet(self, happy: bool = True):
        if happy:
            print("Meow!")
        else:
            raise ValueError("Tried to greet an unhappy cat.")

使用替代方案（NumPy 文档字符串格式）

class Cat(Animal):
    def greet(self, happy: bool = True):
        """Print a greeting from the cat.

        Parameters
        ----------
        happy : bool, optional
            Whether the cat is happy, is True by default.

        Raises
        ------
        ValueError
            If the cat is not happy.
        """
        if happy:
            print("Meow!")
        else:
            raise ValueError("Tried to greet an unhappy cat.")

或者（Google 文档字符串格式）

class Cat(Animal):
    def greet(self, happy: bool = True):
        """Print a greeting from the cat.

        Args:
            happy: Whether the cat is happy, is True by default.

        Raises:
            ValueError: If the cat is not happy.
        """
        if happy:
            print("Meow!")
        else:
            raise ValueError("Tried to greet an unhappy cat.")

Options (选项)

参考