Fix a false positive for missing-param-doc when a method which is…

… decorated with ``typing.overload`` is missing a doc param in its docstring. Closes #9739
pylint-dev · Jun 20, 2024 · cd813b4 · cd813b4
1 parent fc9bdeb
commit cd813b4
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`` when a method which is decorated with ``typing.overload`` is missing a doc param in its docstring.
 
 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
 
 
 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 docstring 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: str | None) -> 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