Fix a false positive for missing-param-doc (#9740)

* Fix a false positive for ``missing-param-doc`` where a method which is decorated with ``typing.overload`` was expected to have a docstring specifying its parameters. Closes #9739 (cherry picked from commit 9cd5c37)
pylint-dev · Jul 15, 2024 · dac28e7 · dac28e7
1 parent bd4c8f1
commit dac28e7
Show file tree

Hide file tree

Showing 4 changed files with 54 additions and 16 deletions.
diff --git a/doc/whatsnew/fragments/9739.false_positive b/doc/whatsnew/fragments/9739.false_positive
@@ -0,0  1,3 @@
 Fix a false positive for ``missing-param-doc`` where a method which is decorated with ``typing.overload`` was expected to have a docstring specifying its parameters.
 
 Closes #9739
diff --git a/pylint/extensions/docparams.py b/pylint/extensions/docparams.py
@@ -196,6  196,9 @@ def visit_functiondef(self, node: nodes.FunctionDef) -> None:
         :param node: Node for a function or method definition in the AST
         :type node: :class:`astroid.scoped_nodes.Function`
         """
         if checker_utils.is_overload_stub(node):
             return
 
         node_doc = utils.docstringify(
             node.doc_node, self.linter.config.default_docstring_type
         )

diff --git a/tests/functional/ext/docparams/missing_param_doc.py b/tests/functional/ext/docparams/missing_param_doc.py
@@ -1,4  1,8 @@
-#pylint: disable=missing-module-docstring
 #pylint: disable=missing-module-docstring, too-few-public-methods
 
 
 from typing import overload, Union
 
 
 def foobar1(arg1, arg2): #[missing-any-param-doc]
     """function foobar ...
@@ -207,3  211,31 @@ def foobar19(one, two, **kwargs):
     """
     print(one, two, kwargs)
     return 1
 
 
 class Word:
     """
     Methods decorated with `typing.overload` are excluded
     from the docparam checks. For example: `missing-param-doc` and
     `missing-type-doc`.
     """
     def __init__(self, word):
         self.word = word
 
     @overload
     def starts_with(self, letter: None) -> None: ...
 
     @overload
     def starts_with(self, letter: str) -> bool: ...
 
     def starts_with(self, letter: Union[str, None]) -> Union[bool, None]:
         """
         Returns:
             True if `self.word` begins with `letter`
 
         Args:
             letter: str
         """
         if self.word:
             return self.word.startswith(letter)
         return None
diff --git a/tests/functional/ext/docparams/missing_param_doc.txt b/tests/functional/ext/docparams/missing_param_doc.txt
@@ -1,15  1,15 @@
-missing-any-param-doc:3:0:3:11:foobar1:"Missing any documentation in ""foobar1""":HIGH
-missing-any-param-doc:8:0:8:11:foobar2:"Missing any documentation in ""foobar2""":HIGH
-missing-param-doc:15:0:15:11:foobar3:"""arg2"" missing in parameter documentation":HIGH
-missing-type-doc:15:0:15:11:foobar3:"""arg2"" missing in parameter type documentation":HIGH
-missing-param-doc:24:0:24:11:foobar4:"""arg2"" missing in parameter documentation":HIGH
-missing-type-doc:24:0:24:11:foobar4:"""arg2"" missing in parameter type documentation":HIGH
-missing-type-doc:33:0:33:11:foobar5:"""arg1"" missing in parameter type documentation":HIGH
-missing-param-doc:43:0:43:11:foobar6:"""arg3"" missing in parameter documentation":HIGH
-missing-type-doc:43:0:43:11:foobar6:"""arg3"" missing in parameter type documentation":HIGH
-missing-any-param-doc:53:0:53:11:foobar7:"Missing any documentation in ""foobar7""":HIGH
-missing-any-param-doc:61:0:61:11:foobar8:"Missing any documentation in ""foobar8""":HIGH
-missing-type-doc:76:0:76:12:foobar10:"""arg1, arg3"" missing in parameter type documentation":HIGH
-missing-any-param-doc:88:0:88:12:foobar11:"Missing any documentation in ""foobar11""":HIGH
-missing-param-doc:97:0:97:12:foobar12:"""arg3"" missing in parameter documentation":HIGH
-missing-type-doc:97:0:97:12:foobar12:"""arg2, arg3"" missing in parameter type documentation":HIGH
 missing-any-param-doc:7:0:7:11:foobar1:"Missing any documentation in ""foobar1""":HIGH
 missing-any-param-doc:12:0:12:11:foobar2:"Missing any documentation in ""foobar2""":HIGH
 missing-param-doc:19:0:19:11:foobar3:"""arg2"" missing in parameter documentation":HIGH
 missing-type-doc:19:0:19:11:foobar3:"""arg2"" missing in parameter type documentation":HIGH
 missing-param-doc:28:0:28:11:foobar4:"""arg2"" missing in parameter documentation":HIGH
 missing-type-doc:28:0:28:11:foobar4:"""arg2"" missing in parameter type documentation":HIGH
 missing-type-doc:37:0:37:11:foobar5:"""arg1"" missing in parameter type documentation":HIGH
 missing-param-doc:47:0:47:11:foobar6:"""arg3"" missing in parameter documentation":HIGH
 missing-type-doc:47:0:47:11:foobar6:"""arg3"" missing in parameter type documentation":HIGH
 missing-any-param-doc:57:0:57:11:foobar7:"Missing any documentation in ""foobar7""":HIGH
 missing-any-param-doc:65:0:65:11:foobar8:"Missing any documentation in ""foobar8""":HIGH
 missing-type-doc:80:0:80:12:foobar10:"""arg1, arg3"" missing in parameter type documentation":HIGH
 missing-any-param-doc:92:0:92:12:foobar11:"Missing any documentation in ""foobar11""":HIGH
 missing-param-doc:101:0:101:12:foobar12:"""arg3"" missing in parameter documentation":HIGH
 missing-type-doc:101:0:101:12:foobar12:"""arg2, arg3"" missing in parameter type documentation":HIGH