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 [email protected]>
pylint-dev · Jul 15, 2024 · 8410f57 · 8410f57
1 parent bd4c8f1
commit 8410f57
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