PyLint/PyLint3 无法识别文档字符串答案

【问题标题】：PyLint/PyLint3 does not recognize docstringsPyLint/PyLint3 无法识别文档字符串
【发布时间】：2019-07-19 22:56:41
【问题描述】：

我编写了以下格式的几个 Python 3 模块：

def some_module():
'''Do something.

Parameters
----------
Returns
-------
'''
# Some code

当我对文件运行 PyLint 或 PyLint3 时，我收到以下错误：

****************** 模块 some_module.some_module
C: 1, 0: 缺少模块文档字符串（missing-docstring）

我做错了什么？ PyLint 是否需要特定的文档字符串样式？

【问题讨论】：

您的示例是一个函数文档字符串，pylint 要求您记录模块本身。
我从this question 了解到，函数包含特定任务的可重用代码，而模块是函数、类等的捆绑。但在这种情况下，所有模块都只包含一个函数，所以有不需要模块级文档字符串。 PyLint 能够理解这一点吗？或者甚至简单的函数也应该同时具有模块和函数文档字符串？或者我应该避免创建太多的函数，而是将它们捆绑到模块中？
另外，从this 的讨论中，还不清楚函数文档字符串与模块文档字符串的区别。难道 PEP 8 和 PEP 257 只与大型项目的组织相关，而对小型脚本的价值有限？
简单来说，模块就是 .py 文件。 Pylint 并没有真正“理解”任何东西，它只是根据一堆规则（静态地）检查你的代码。特别是，missing-docstring 检查模块、类和函数是否具有文档字符串（即__doc__）。是否要执行这些规则取决于您。例如，我发现too-few-public-methods 非常没用，所以我通常禁用它。
好的，我明白了。谢谢！

【解决方案1】：

您是否尝试过缩进文档字符串，以便将其识别为模块的一部分？

def some_module():
    '''Do something.

    Parameters
    ----------
    Returns
    -------
    '''
    # Some code
    ...

【讨论】：