diff --git a/doc/whatsnew/fragments/9739.false_positive b/doc/whatsnew/fragments/9739.false_positive new file mode 100644 index 0000000000..29cbab4c8e --- /dev/null +++ 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 index 8e1987f7c9..5d672131a2 100644 --- 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 index dbd5846fc6..c039c07ffc 100644 --- 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 index fdf4da93f4..0fddc295f9 100644 --- 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