跳到内容

未文档化的公共类 (D101)

源自 pydocstyle 代码检查器。

作用

检查未文档化的公共类定义。

为什么这不好?

公共类应该通过文档字符串来记录,以概述其目的和行为。

一般来说,类文档字符串应该描述类的目的,并列出其公共属性和方法。

如果代码库遵循类文档字符串的标准格式,请遵循该格式以保持一致性。

示例

class Player:
    def __init__(self, name: str, points: int = 0) -> None:
        self.name: str = name
        self.points: int = points

    def add_points(self, points: int) -> None:
        self.points += points

例如使用(NumPy 文档字符串格式)

class Player:
    """A player in the game.

    Attributes
    ----------
    name : str
        The name of the player.
    points : int
        The number of points the player has.

    Methods
    -------
    add_points(points: int) -> None
        Add points to the player's score.
    """

    def __init__(self, name: str, points: int = 0) -> None:
        self.name: str = name
        self.points: int = points

    def add_points(self, points: int) -> None:
        self.points += points

或者(Google 文档字符串格式)

class Player:
    """A player in the game.

    Attributes:
        name: The name of the player.
        points: The number of points the player has.
    """

    def __init__(self, name: str, points: int = 0) -> None:
        self.name: str = name
        self.points: int = points

    def add_points(self, points: int) -> None:
        self.points += points

参考