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

* 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)

Co-authored-by: Mark Byrne <31762852+mbyrnepr2@users.noreply.github.com>

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

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
         )

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

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