python - 如何在 Pylint 的文件级别禁用 "missing docstring"警告？

Question

Pylint 会抛出一些文件缺少文档字符串的错误。我尝试将文档字符串添加到每个类、方法和函数，但似乎 Pylint 还检查文件是否应该在它们的开头有一个文档字符串。我可以以某种方式禁用它吗？

我希望收到有关类、函数或方法中缺少文档字符串的通知，但文件不应强制要求具有文档字符串。

(在专有源文件的开头是否经常出现法律术语的术语？有例子吗？我不知道单独发布这样一个琐碎的问题是否可以。)

Answer 1

Python 模块最好有一个文档字符串，解释模块的作用、提供的功能以及如何使用类的示例。这与您经常在文件开头看到的提供版权和许可信息的注释不同，IMO 不应将其放入文档字符串中(有些人甚至认为它们应该完全消失，例如 Get Rid of Source Code Templates )

使用 Pylint 2.4 及更高版本，您可以使用以下三个子消息来区分各种 missing-docstring:

• C0114 (missing-module-docstring)
• C0115 (missing-class-docstring)
• C0116 (missing-function-docstring)

所以下面的 .pylintrc 文件应该可以工作:

[MASTER]
disable=
    C0114, # missing-module-docstring

对于以前的 Pylint 版本，它没有针对可能出现文档字符串的各个位置的单独代码，因此您所能做的就是禁用 C0111。问题是，如果你在模块范围内禁用它，那么它将在模块中的任何地方被禁用(即，你不会因为缺少函数/类/方法文档字符串而获得任何 C 行。这可以说是不好的。

所以我建议添加缺少的小文档字符串，例如:

"""
high level support for doing this and that.
"""

很快，您就会发现有用的东西可以放入其中，例如提供如何使用模块的各种类/函数的示例，这些类/函数不一定属于类/函数的各个文档字符串(例如就像它们之间的交互方式，或者类似快速入门指南之类的东西)。