企业官网建设流程全解析

• 静态分析
• 代码质量
• Lint
• 开发工具

导读

missing-return-type-doc（W9012）是 Pylint 官方扩展docparams提供的一条文档规范检查消息，用于在函数返回非None值且 docstring 中缺失返回类型声明（如 Sphinx 的:rtype:）时发出警告。它只在配置项accept-no-return-doc被显式设为no时才会触发，本文将从消息定义、触发条件、源码判定逻辑、三种主流 docstring 风格的写法以及测试证据等维度，带你完整掌握这条消息的启用方式与修复方法。

消息定义与所属插件

missing-return-type-doc属于 Pylint 的parameter_documentation检查器（checker），该检查器由官方扩展插件 pylint/extensions/docparams.py 提供，用于校验 Sphinx、Google、Numpy 三种风格的 docstring。在 pylint/extensions/docparams.py 中，该消息被定义为：

"W9012": ( "Missing return type documentation", "missing-return-type-doc", "Please document the type returned by this method.", ),

其消息类型为W（Warning，警告），对应的官方文档页位于 extensions.rst。要启用这条消息，需要在配置中通过load-plugins=pylint.extensions.docparams加载扩展插件（详见 missing-return-type-doc 的示例配置）。

触发条件：核心开关 accept-no-return-doc

官方消息文档 details.rst 只有一句话，却点明了这条消息的命门：

This message is raised only when parameteraccept-no-return-docis set tono.

也就是说，missing-return-type-doc默认不会触发。插件对"函数有返回值但 docstring 里完全没有返回文档"这件事默认持宽容态度，只有当你把accept-no-return-doc设为no，强制要求每个有返回值的函数都必须写出返回文档时，这条消息（及其姊妹消息missing-return-doc）才会被激活。

配置项的源码定义

在 pylint/extensions/docparams.py 中，accept-no-return-doc的定义如下：

( "accept-no-return-doc", { "default": True, "type": "yn", "metavar": "<y or n>", "help": "Whether to accept totally missing return " "documentation in the docstring of a function that " "returns a statement.", }, ),

关键信息：

• 默认值为True：即默认接受"函数有返回值但 docstring 完全没写返回说明"的情况；
• 取值类型为yn：只能填yes/no、y/n或true/false这类布尔值；
• 语义：当函数体内存在return语句时，是否允许 docstring 中完全没有返回相关的说明。

与它并列的还有accept-no-param-doc（参数文档开关）、accept-no-raise-doc（异常文档开关）和accept-no-yields-doc（生成器 yield 文档开关），它们共享相同的yn类型与默认值True，共同组成docparams插件的"宽松度控制组"。

三种配置方式

方式一：pylintrc 文件（官方示例 pylintrc）：

[main] load-plugins=pylint.extensions.docparams [Parameter_documentation] accept-no-return-doc=no

方式二：pyproject.toml（PEP 621 风格的tool.pylint配置）：

[tool.pylint.main] load-plugins = "pylint.extensions.docparams" [tool.pylint."Parameter_documentation"] accept-no-return-doc = "no"

方式三：命令行直接传入：

pylint --load-plugins=pylint.extensions.docparams \ --accept-no-return-doc=no your_module.py

注意：在命令行中传递yn类型参数时同样使用no或yes字样。

官方示例：bad 与 good 对照

Pylint 官方消息库为这条消息准备了成对的示例文件，位于 doc/data/messages/m/missing-return-type-doc/。

触发警告的写法（bad.py）

bad.py：

def integer_sum(a: int, b: int): # [missing-return-type-doc] """Returns sum of two integers :param a: first integer :param b: second integer :return: sum of parameters a and b """ return a + b

这个函数虽然已经在 docstring 里用:return:写明了"返回什么"，签名中也有a: int, b: int的参数类型标注，但存在两个缺口：

1. docstring 中缺少:rtype:字段，即没有在文档中声明返回类型；
2. 函数签名缺少-> int的返回类型标注——在 visit_return 的实现 中，函数没有返回类型注解（func_node.returns为None）时，检查器会继续要求 docstring 中必须存在返回类型声明，于是报出missing-return-type-doc。

通过检查的写法（good.py）

good.py：

def integer_sum(a: int, b: int) -> int: """Returns sum of two integers :param a: first integer :param b: second integer :return: sum of parameters a and b """ return a + b

唯一的差异是补上了-> int返回类型标注。这正对应源码中的关键逻辑：只要函数签名里有返回类型注解（func_node.returns或type_comment_returns），就无需再在 docstring 里重复写:rtype:。

源码级判定逻辑剖析

missing-return-type-doc的判定入口是 pylint/extensions/docparams.py 中的visit_return方法，整体流程如下：

def visit_return(self, node: nodes.Return) -> None: if not utils.returns_something(node): return # ① 返回 None 或裸 return，跳过 if self.linter.config.accept_no_return_doc: return # ② 开关为 yes，直接放过 func_node: nodes.FunctionDef = node.frame() # ③ 匹配 no-docstring-rgx 的函数跳过 no_docstring_rgx = self.linter.config.no_docstring_rgx if no_docstring_rgx and re.match(no_docstring_rgx, func_node.name): return doc = utils.docstringify( func_node.doc_node, self.linter.config.default_docstring_type ) is_property = checker_utils.decorated_with_property(func_node) # ④ 没有"返回说明"，报 missing-return-doc if not (doc.has_returns() or (doc.has_property_returns() and is_property)): self.add_message("missing-return-doc", node=func_node, confidence=HIGH) # ⑤ 已有返回类型注解则不需要 :rtype: if func_node.returns or func_node.type_comment_returns: return # ⑥ 没有"返回类型说明"，报 missing-return-type-doc if not (doc.has_rtype() or (doc.has_property_type() and is_property)): self.add_message("missing-return-type-doc", node=func_node, confidence=HIGH)

逐层拆解：

1. 先看是否"真的返回了值"：utils.returns_something()定义在 pylint/extensions/_check_docs_utils.py，它判定return节点是否有非None的值——裸return和return None都会被过滤掉，因此"返回None的函数不需要返回文档"；
2. 再看开关：accept-no-return-doc为真（默认值True）时直接结束访问，这正是"只有设为no才报错"的源码根因；
3. 函数名豁免：匹配no-docstring-rgx正则（如默认的私有函数下划线前缀规则）的函数被跳过，测试文件 missing_return_doc_required.py 中的_function就展示了这一豁免；
4. 区分两条消息：missing-return-doc（W9011）针对"没有描述返回什么"，missing-return-type-doc（W9012）针对"没有声明返回类型"，二者可以同时触发（详见下文测试一节）；
5. 类型注解优先：函数签名已写-> T或type_comment时，docstring 不必再写:rtype:——这是官方 bad/good 示例的核心差异；
6. property 特殊处理：对@property装饰的函数，判定改用has_property_returns()与has_property_type()，即允许用 property 自己的 docstring 承担返回文档职责。

Docstring 的"是否包含返回/类型说明"由基类Docstring及各风格子类实现（pylint/extensions/_check_docs_utils.py）。以 Sphinx 为例，has_returns()通过正则:returns?:匹配:return:/:returns:字段，has_rtype()通过:rtype:匹配（pylint/extensions/_check_docs_utils.py）。

三种 docstring 风格的"返回类型"写法

docparams支持 Sphinx、Google、Numpy 三种风格（由default-docstring-type决定无法自动识别时的回退风格），官方测试覆盖了三种风格在accept-no-return-doc=no下的完整行为，以下写法均可避免missing-return-type-doc。

Sphinx 风格：:rtype:字段

def my_func(self): """find_sphinx_returns :return: Always False :rtype: bool """ return False

当签名没有->注解时，:rtype: bool就是检查器唯一认可的返回类型声明。如果只写了:return:而没有:rtype:，则会触发 missing-return-type-doc 对应的测试用例。

Google 风格：Returns:段中的类型:前缀

def my_func(self): """Warn partial google returns Returns: bool: Always False """ return False

Google 风格要求Returns:段中先写类型再接冒号和描述（bool: ...）；反之，只写描述不写类型会触发missing-return-type-doc，只写类型不写描述会触发missing-return-doc，两种缺陷在 missing_return_doc_required_Google.py 中都有对应的"部分缺失"用例。

Numpy 风格：Returns段下划线标题 + 类型行

def my_func(self, doc_type): """warn_partial_numpy_returns_type Arguments --------- doc_type : str Numpy Returns ------- bool """ return False

Numpy 风格在Returns标题下方的类型行（如bool）即视为返回类型声明。若只写了Returns标题而类型行缺描述，会报missing-return-doc；整个Returns段缺失时两条消息同时出现，参见 missing_return_doc_required_Numpy.py。

何时两条消息同时出现

missing-return-doc与missing-return-type-doc是相互独立的两个检查：前者检查"返回值的含义描述"，后者检查"返回值的类型声明"。当函数有非None返回值、accept-no-return-doc=no、且 docstring 中既无返回描述也无返回类型时，两条消息会同时报出。官方测试 missing_return_doc_required.txt 给出了预期输出：

missing-return-doc:6:0:6:22:warns_no_docstring:Missing return documentation:HIGH missing-return-type-doc:6:0:6:22:warns_no_docstring:Missing return type documentation:HIGH

其中被触发的是 missing_return_doc_required.py 中第 6 行的warns_no_docstring函数——它既不写 docstring，也没有返回类型注解。注意该测试通过 missing_return_doc_required.rc 加载插件并设置accept-no-return-doc=no，与官方消息库示例的配置方式完全一致。

常见豁免与边界情况

结合源码与测试，以下几类函数即使accept-no-return-doc=no也不会触发该消息：

• 返回None的函数：return None或裸return被returns_something()过滤（pylint/extensions/_check_docs_utils.py）；
• 签名带返回注解的函数：-> T或 type comment 一旦存在，就不再要求 docstring 写:rtype:；
• 匹配no-docstring-rgx的函数：如以下划线开头的私有函数_function；
• @property的 setter：setter 的返回文档职责转移到对应 property 的 docstring（get_setters_property逻辑见 pylint/extensions/_check_docs_utils.py）；
• 函数体过短（受docstring-min-length约束）或匹配no-docstring-rgx的情况在visit_functiondef入口处即被跳过（pylint/extensions/docparams.py）。

总结：从"宽松"到"严格"的启用路径

missing-return-type-doc是一条默认关闭、需要显式开启的文档强制消息。开启的完整路径是：加载pylint.extensions.docparams插件 → 将accept-no-return-doc设为no→ 为每个有非None返回值的函数补齐返回文档。补齐时有两条捷径：要么在函数签名中写出-> 类型注解，要么按所用 docstring 风格（Sphinx 的:rtype:、Google 的Returns:类型前缀、Numpy 的Returns类型行）在文档中声明返回类型。仓库中的官方示例 bad.py 与 good.py 只差一个-> int注解，恰好演示了这条消息最典型的修复方式。

• 静态分析
• 代码质量
• Lint
• 开发工具