Skip to content

Commit

Permalink
Fix a false positive for missing-param-doc (#9740)
Browse files Browse the repository at this point in the history
* 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)
  • Loading branch information
mbyrnepr2 authored and github-actions[bot] committed Jul 15, 2024
1 parent bd4c8f1 commit dac28e7
Show file tree
Hide file tree
Showing 4 changed files with 54 additions and 16 deletions.
3 changes: 3 additions & 0 deletions doc/whatsnew/fragments/9739.false_positive
Original file line number Diff line number Diff line change
@@ -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
3 changes: 3 additions & 0 deletions pylint/extensions/docparams.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
)
Expand Down
34 changes: 33 additions & 1 deletion tests/functional/ext/docparams/missing_param_doc.py
Original file line number Diff line number Diff line change
@@ -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 ...
Expand Down Expand Up @@ -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
30 changes: 15 additions & 15 deletions tests/functional/ext/docparams/missing_param_doc.txt
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit dac28e7

Please sign in to comment.