diff options
author | Pierre Sassoulas <pierre.sassoulas@gmail.com> | 2021-06-25 10:16:13 +0200 |
---|---|---|
committer | Pierre Sassoulas <pierre.sassoulas@gmail.com> | 2021-06-25 14:34:48 +0200 |
commit | ce987fdc26bc30611e8e91af1492918175f9af58 (patch) | |
tree | eeff81668e24ef4e99871c85db35077cc19d9364 | |
parent | 1ff8184e05bd972c1f343fdf7043b4823fc0f2b1 (diff) | |
download | pylint-git-ce987fdc26bc30611e8e91af1492918175f9af58.tar.gz |
Fix useless-type-doc false positive when args exist in the docstring
Closes #4117
Closes #4593
-rw-r--r-- | pylint/extensions/_check_docs_utils.py | 4 | ||||
-rw-r--r-- | pylint/extensions/docparams.py | 14 | ||||
-rw-r--r-- | tests/functional/u/useless/useless_type_doc.py | 51 | ||||
-rw-r--r-- | tests/functional/u/useless/useless_type_doc.rc | 8 |
4 files changed, 74 insertions, 3 deletions
diff --git a/pylint/extensions/_check_docs_utils.py b/pylint/extensions/_check_docs_utils.py index de2f427bf..5f1e8ea0b 100644 --- a/pylint/extensions/_check_docs_utils.py +++ b/pylint/extensions/_check_docs_utils.py @@ -25,6 +25,7 @@ import re from typing import List import astroid +from astroid import AssignName from pylint.checkers import utils @@ -206,6 +207,9 @@ class Docstring: def __repr__(self) -> str: return f"<{self.__class__.__name__}:'''{self.doc}'''>" + def arg_is_documented(self, arg_name: AssignName) -> bool: + return arg_name.name in self.doc + def is_valid(self): return False diff --git a/pylint/extensions/docparams.py b/pylint/extensions/docparams.py index b53802bce..032e993a6 100644 --- a/pylint/extensions/docparams.py +++ b/pylint/extensions/docparams.py @@ -23,12 +23,14 @@ """Pylint plugin for checking in Sphinx, Google, or Numpy style docstrings """ import re +from typing import Optional import astroid from pylint.checkers import BaseChecker from pylint.checkers import utils as checker_utils from pylint.extensions import _check_docs_utils as utils +from pylint.extensions._check_docs_utils import Docstring from pylint.interfaces import IAstroidChecker from pylint.utils import get_global_option @@ -460,7 +462,11 @@ class DocstringParameterChecker(BaseChecker): ) def check_arguments_in_docstring( - self, doc, arguments_node, warning_node, accept_no_param_doc=None + self, + doc: Docstring, + arguments_node: astroid.Arguments, + warning_node: astroid.NodeNG, + accept_no_param_doc: Optional[bool] = None, ): """Check that all parameters in a function, method or class constructor on the one hand and the parameters mentioned in the parameter @@ -541,10 +547,12 @@ class DocstringParameterChecker(BaseChecker): ) for index, arg_name in enumerate(arguments_node.args): - if arguments_node.annotations[index]: + if arguments_node.annotations[index] and doc.arg_is_documented(arg_name): params_with_type.add(arg_name.name) for index, arg_name in enumerate(arguments_node.kwonlyargs): - if arguments_node.kwonlyargs_annotations[index]: + if arguments_node.kwonlyargs_annotations[index] and doc.arg_is_documented( + arg_name + ): params_with_type.add(arg_name.name) if not tolerate_missing_params: diff --git a/tests/functional/u/useless/useless_type_doc.py b/tests/functional/u/useless/useless_type_doc.py new file mode 100644 index 000000000..88dedb479 --- /dev/null +++ b/tests/functional/u/useless/useless_type_doc.py @@ -0,0 +1,51 @@ +"""demonstrate FP with useless-type-doc""" +# line-too-long + + +def function(public_param: int, _some_private_param: bool = False) -> None: + """does things + + Args: + public_param: an ordinary parameter + """ + for _ in range(public_param): + ... + if _some_private_param: + ... + else: + ... + + +# +1: [useless-type-doc,useless-param-doc] +def function_useless_doc(public_param: int, _some_private_param: bool = False) -> None: + """does things + + Args: + public_param: an ordinary parameter + _some_private_param (bool): private param + + """ + for _ in range(public_param): + ... + if _some_private_param: + ... + else: + ... + + +def test(_new: str) -> str: # We don't expect useless-type-doc here + """foobar + + :return: comment + """ + return "" + + +# +1: [useless-type-doc,useless-param-doc] +def test_two(_new: str) -> str: # We don't expect useless-type-doc here + """foobar + + :param str _new: + :return: comment + """ + return "" diff --git a/tests/functional/u/useless/useless_type_doc.rc b/tests/functional/u/useless/useless_type_doc.rc new file mode 100644 index 000000000..d4a6dc172 --- /dev/null +++ b/tests/functional/u/useless/useless_type_doc.rc @@ -0,0 +1,8 @@ +[MASTER] +load-plugins=pylint.extensions.docparams, + +[PARAMETER_DOCUMENTATION] +accept-no-param-doc=no +accept-no-raise-doc=no +accept-no-return-doc=no +accept-no-yields-doc=no |