跳到内容

未文档化的魔术方法 (D105)

源自 pydocstyle 代码检查器。

作用

检查未文档化的魔术方法定义。

为什么这不好？

魔术方法（名称以双下划线开头和结尾的方法）用于实现运算符重载和其他特殊行为。 这些方法应通过文档字符串记录其行为。

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

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

示例

class Cat(Animal):
    def __str__(self) -> str:
        return f"Cat: {self.name}"


cat = Cat("Dusty")
print(cat)  # "Cat: Dusty"

建议改为

class Cat(Animal):
    def __str__(self) -> str:
        """Return a string representation of the cat."""
        return f"Cat: {self.name}"


cat = Cat("Dusty")
print(cat)  # "Cat: Dusty"

Options (选项)

参考