如何在Pylint中按文件禁用“缺少文档字符串”警告？

Question

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

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

（有没有一个专门的术语来描述那些通常出现在专有源文件开头的法律术语？有没有例子？我不知道是否可以单独提出这样一个琐碎的问题。）

Answer 1

只需在你想要关闭这些警告的文件开头加上以下几行代码。

# pylint: disable=missing-module-docstring
# pylint: disable=missing-class-docstring
# pylint: disable=missing-function-docstring

Answer 2

正如followben在评论中提到的，解决这个问题的更好方法是直接禁用我们想要关闭的规则，而不是使用--errors-only。我们可以通过--disable=<msg ids>, -d <msg ids>来实现。

你可以在这里找到消息ID的列表。对于问题中提到的具体错误，消息ID是C0111。

在你选择的IDE或文本编辑器中使用--disable=参数时，你需要找出如何操作。

在VS Code中，可以通过在settings.json中添加以下内容来实现：

"python.linting.pylintArgs": ["--disable=C0111"]

Answer 3

对于一个Python模块来说，写一个文档字符串（docstring）是很有用的，它可以解释这个模块的功能、提供的内容，以及如何使用里面的类的示例。这和你常在文件开头看到的版权和许可信息的注释是不同的，我认为这些信息不应该放在文档字符串里（有些人甚至认为这些信息应该完全去掉，参见例如 去掉源代码模板）。

在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.
"""

很快，你会发现可以在里面放一些有用的东西，比如提供如何使用模块中各种类/函数的示例，这些示例不一定要放在各个类/函数的文档字符串里（比如它们之间如何互动，或者像快速入门指南这样的内容）。