如何禁用“缺少文档字符串"?Pylint 中文件级别的警告? [英] How do I disable "missing docstring" warnings at a file-level in Pylint?

问题描述

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

Pylint throws errors that some of the files are missing docstrings. I try and add docstrings to each class, method and function, but it seems that Pylint also checks that files should have a docstring at the beginning of them. Can I disable this somehow?

我希望收到有关类、函数或方法中缺少文档字符串的通知，但文件必须具有文档字符串并不是强制性的.

I would like to be notified of a docstring is missing inside a class, function or method, but it shouldn't be mandatory for a file to have a docstring.

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

(Is there a term for the legal jargon often found at the beginning of a proprietary source file? Any examples? I don't know whether it is a okay to post such a trivial question separately.)

推荐答案

Python 模块最好有一个文档字符串，用于解释模块的功能、提供的功能以及如何使用类的示例.这与您经常在提供版权和许可信息的文件开头看到的注释不同，IMO 不应将其放在文档字符串中(有些人甚至认为它们应该完全消失，参见例如 摆脱源代码模板)

It is nice for a Python module to have a docstring, explaining what the module does, what it provides, examples of how to use the classes. This is different from the comments that you often see at the beginning of a file giving the copyright and license information, which IMO should not go in the docstring (some even argue that they should disappear altogether, see e.g. Get Rid of Source Code Templates)

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

With Pylint 2.4 and above, you can differentiate between the various missing-docstring by using the three following sub-messages:

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

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

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

So the following .pylintrc file should work:

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

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

For previous versions of Pylint, it does not have a separate code for the various place where docstrings can occur, so all you can do is disable C0111. The problem is that if you disable this at module scope, then it will be disabled everywhere in the module (i.e., you won't get any C line for missing function / class / method docstring. Which arguably is not nice.

所以我建议添加那个小的缺失的文档字符串，比如:

So I suggest adding that small missing docstring, saying something like:

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

很快，您就会发现有用的东西可以放在那里，例如提供有关如何使用模块的各种类/函数的示例，这些类/函数不一定属于类/函数的各个文档字符串(例如了解它们如何相互作用，或者诸如快速入门指南之类的东西).

Soon enough, you'll be finding useful things to put in there, such as providing examples of how to use the various classes / functions of the module which do not necessarily belong to the individual docstrings of the classes / functions (such as how these interact, or something like a quick start guide).

这篇关于如何禁用“缺少文档字符串"?Pylint 中文件级别的警告?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！