Make missing-return-doc respect the no-docstring-rgx option (#…

…7410)
pylint-dev · Sep 6, 2022 · fb3a641 · fb3a641
1 parent 40a53aa
commit fb3a641
Show file tree

Hide file tree

Showing 6 changed files with 54 additions and 22 deletions.
diff --git a/doc/whatsnew/fragments/4743.bugfix b/doc/whatsnew/fragments/4743.bugfix
@@ -0,0 +1,3 @@
+``missing-return-doc`` now respects the ``no-docstring-rgx`` option.
+
+Closes #4743
diff --git a/pylint/extensions/docparams.py b/pylint/extensions/docparams.py
@@ -327,6 +327,11 @@ def visit_return(self, node: nodes.Return) -> None:
         if not isinstance(func_node, astroid.FunctionDef):
             return
 
+        # skip functions that match the 'no-docstring-rgx' config option
+        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
         )

diff --git a/tests/functional/ext/docparams/docparams.py b/tests/functional/ext/docparams/docparams.py
@@ -1,39 +1,49 @@
 """Fixture for testing missing documentation in docparams."""
 
 
-def _private_func1(param1):  # [missing-return-doc, missing-return-type-doc]
+def _private_func1(  # [missing-return-doc, missing-return-type-doc, missing-any-param-doc]
+    param1,
+):
     """This is a test docstring without returns"""
     return param1
 
 
-def _private_func2(param1):  # [missing-yield-doc, missing-yield-type-doc]
+def _private_func2(  # [missing-yield-doc, missing-yield-type-doc, missing-any-param-doc]
+    param1,
+):
     """This is a test docstring without yields"""
     yield param1
 
 
-def _private_func3(param1):  # [missing-raises-doc]
+def _private_func3(param1):  # [missing-raises-doc, missing-any-param-doc]
     """This is a test docstring without raises"""
-    raise Exception('Example')
+    raise Exception("Example")
 
 
 def public_func1(param1):  # [missing-any-param-doc]
     """This is a test docstring without params"""
     print(param1)
 
 
-async def _async_private_func1(param1):  # [missing-return-doc, missing-return-type-doc]
+# pylint: disable-next=line-too-long
+async def _async_private_func1(  # [missing-return-doc, missing-return-type-doc, missing-any-param-doc]
+    param1,
+):
     """This is a test docstring without returns"""
     return param1
 
 
-async def _async_private_func2(param1):  # [missing-yield-doc, missing-yield-type-doc]
+# pylint: disable-next=line-too-long
+async def _async_private_func2(  # [missing-yield-doc, missing-yield-type-doc, missing-any-param-doc]
+    param1,
+):
     """This is a test docstring without yields"""
     yield param1
 
 
-async def _async_private_func3(param1):  # [missing-raises-doc]
+async def _async_private_func3(param1):  # [missing-raises-doc, missing-any-param-doc]
     """This is a test docstring without raises"""
-    raise Exception('Example')
+    raise Exception("Example")
 
 
 async def async_public_func1(param1):  # [missing-any-param-doc]

diff --git a/tests/functional/ext/docparams/docparams.rc b/tests/functional/ext/docparams/docparams.rc
@@ -1,5 +1,6 @@
 [MAIN]
 load-plugins = pylint.extensions.docparams
+no-docstring-rgx = ONLYVERYSPECIFICFUNCTIONS
 
 [BASIC]
 accept-no-param-doc = no

diff --git a/tests/functional/ext/docparams/docparams.txt b/tests/functional/ext/docparams/docparams.txt
@@ -1,16 +1,22 @@
+missing-any-param-doc:4:0:4:18:_private_func1:"Missing any documentation in ""_private_func1""":HIGH
 missing-return-doc:4:0:4:18:_private_func1:Missing return documentation:HIGH
 missing-return-type-doc:4:0:4:18:_private_func1:Missing return type documentation:HIGH
-missing-yield-doc:9:0:9:18:_private_func2:Missing yield documentation:HIGH
-missing-yield-type-doc:9:0:9:18:_private_func2:Missing yield type documentation:HIGH
-missing-raises-doc:14:0:14:18:_private_func3:"""Exception"" not documented as being raised":HIGH
-missing-any-param-doc:19:0:19:16:public_func1:"Missing any documentation in ""public_func1""":HIGH
-missing-return-doc:24:0:24:30:_async_private_func1:Missing return documentation:HIGH
-missing-return-type-doc:24:0:24:30:_async_private_func1:Missing return type documentation:HIGH
-missing-yield-doc:29:0:29:30:_async_private_func2:Missing yield documentation:HIGH
-missing-yield-type-doc:29:0:29:30:_async_private_func2:Missing yield type documentation:HIGH
-missing-raises-doc:34:0:34:30:_async_private_func3:"""Exception"" not documented as being raised":HIGH
-missing-any-param-doc:39:0:39:28:async_public_func1:"Missing any documentation in ""async_public_func1""":HIGH
-differing-param-doc:44:0:44:23:differing_param_doc:"""param"" differing in parameter documentation":HIGH
-differing-param-doc:55:0:55:35:differing_param_doc_kwords_only:"""param"" differing in parameter documentation":HIGH
-missing-type-doc:66:0:66:20:missing_type_doc:"""par1"" missing in parameter type documentation":HIGH
-missing-type-doc:76:0:76:32:missing_type_doc_kwords_only:"""par1"" missing in parameter type documentation":HIGH
+missing-any-param-doc:11:0:11:18:_private_func2:"Missing any documentation in ""_private_func2""":HIGH
+missing-yield-doc:11:0:11:18:_private_func2:Missing yield documentation:HIGH
+missing-yield-type-doc:11:0:11:18:_private_func2:Missing yield type documentation:HIGH
+missing-any-param-doc:18:0:18:18:_private_func3:"Missing any documentation in ""_private_func3""":HIGH
+missing-raises-doc:18:0:18:18:_private_func3:"""Exception"" not documented as being raised":HIGH
+missing-any-param-doc:23:0:23:16:public_func1:"Missing any documentation in ""public_func1""":HIGH
+missing-any-param-doc:29:0:29:30:_async_private_func1:"Missing any documentation in ""_async_private_func1""":HIGH
+missing-return-doc:29:0:29:30:_async_private_func1:Missing return documentation:HIGH
+missing-return-type-doc:29:0:29:30:_async_private_func1:Missing return type documentation:HIGH
+missing-any-param-doc:37:0:37:30:_async_private_func2:"Missing any documentation in ""_async_private_func2""":HIGH
+missing-yield-doc:37:0:37:30:_async_private_func2:Missing yield documentation:HIGH
+missing-yield-type-doc:37:0:37:30:_async_private_func2:Missing yield type documentation:HIGH
+missing-any-param-doc:44:0:44:30:_async_private_func3:"Missing any documentation in ""_async_private_func3""":HIGH
+missing-raises-doc:44:0:44:30:_async_private_func3:"""Exception"" not documented as being raised":HIGH
+missing-any-param-doc:49:0:49:28:async_public_func1:"Missing any documentation in ""async_public_func1""":HIGH
+differing-param-doc:54:0:54:23:differing_param_doc:"""param"" differing in parameter documentation":HIGH
+differing-param-doc:65:0:65:35:differing_param_doc_kwords_only:"""param"" differing in parameter documentation":HIGH
+missing-type-doc:76:0:76:20:missing_type_doc:"""par1"" missing in parameter type documentation":HIGH
+missing-type-doc:86:0:86:32:missing_type_doc_kwords_only:"""par1"" missing in parameter type documentation":HIGH
diff --git a/tests/functional/ext/docparams/return/missing_return_doc_required.py b/tests/functional/ext/docparams/return/missing_return_doc_required.py
@@ -5,3 +5,10 @@
 
 def warns_no_docstring(self):  # [missing-return-doc, missing-return-type-doc]
     return False
+
+
+# this function doesn't require a docstring, because its name starts
+# with an '_' (no-docstring-rgx):
+def _function(some_arg: int) -> int:
+    _ = some_arg
+    return 0