From f56c62cdc6d8684211387b6e1dc3e256b6f031ed Mon Sep 17 00:00:00 2001 From: mpernigo Date: Sun, 19 Jun 2022 13:00:30 +0200 Subject: [PATCH 1/7] Read `posonly` args and annotations on `check_arguments_in_docstring` --- pylint/extensions/docparams.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/pylint/extensions/docparams.py b/pylint/extensions/docparams.py index 35c847e0b1..c3253c89ec 100644 --- a/pylint/extensions/docparams.py +++ b/pylint/extensions/docparams.py @@ -525,6 +525,7 @@ class constructor. # Collect the function arguments. expected_argument_names = {arg.name for arg in arguments_node.args} expected_argument_names.update(arg.name for arg in arguments_node.kwonlyargs) + expected_argument_names.update(arg.name for arg in arguments_node.posonlyargs) not_needed_type_in_docstring = self.not_needed_param_in_docstring.copy() expected_but_ignored_argument_names = set() @@ -562,6 +563,9 @@ class constructor. for index, arg_name in enumerate(arguments_node.kwonlyargs): if arguments_node.kwonlyargs_annotations[index]: params_with_type.add(arg_name.name) + for index, arg_name in enumerate(arguments_node.posonlyargs): + if arguments_node.posonlyargs_annotations[index]: + params_with_type.add(arg_name.name) if not tolerate_missing_params: missing_param_doc = (expected_argument_names - params_with_doc) - ( From fb6d31d76387e296770ab11ced8bfbfe1760c080 Mon Sep 17 00:00:00 2001 From: mpernigo Date: Sun, 19 Jun 2022 14:12:53 +0200 Subject: [PATCH 2/7] Add fix to `2.15/index.rst` --- doc/whatsnew/2/2.15/index.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/whatsnew/2/2.15/index.rst b/doc/whatsnew/2/2.15/index.rst index 46fa821929..69beee7a76 100644 --- a/doc/whatsnew/2/2.15/index.rst +++ b/doc/whatsnew/2/2.15/index.rst @@ -27,6 +27,9 @@ Extensions False positives fixed ===================== +* The ``differing-param-doc`` check was triggered by positional only arguments. + + Closes #6950 False negatives fixed ===================== From 5303e50159565680f4ceb379973c41d356a7b08d Mon Sep 17 00:00:00 2001 From: mpernigo Date: Sun, 19 Jun 2022 17:53:00 +0200 Subject: [PATCH 3/7] Add test cases to the docparams functional tests --- tests/functional/ext/docparams/docparams.py | 63 ++++++++++++++++++++ tests/functional/ext/docparams/docparams.txt | 6 ++ 2 files changed, 69 insertions(+) diff --git a/tests/functional/ext/docparams/docparams.py b/tests/functional/ext/docparams/docparams.py index 8dbb0295af..6e14cba2ad 100644 --- a/tests/functional/ext/docparams/docparams.py +++ b/tests/functional/ext/docparams/docparams.py @@ -39,3 +39,66 @@ async def _async_private_func3(param1): # [missing-raises-doc] async def async_public_func1(param1): # [missing-any-param-doc] """This is a test docstring without params""" print(param1) + + +def differing_param_doc(par1: int) -> int: # [differing-param-doc] + """This is a test docstring documenting one non-existing param + + :param par1: some param + :param param: some param + :return: the sum of the params + """ + + return par1 + + +def differing_param_doc_kwords_only(*, par1: int) -> int: # [differing-param-doc] + """This is a test docstring documenting one non-existing param + + :param par1: some param + :param param: some param + :return: the sum of the params + """ + + return par1 + + +def differing_param_doc_pos_only(par1: int, /) -> int: # [differing-param-doc] + """This is a test docstring documenting one non-existing param + + :param par1: some param + :param param: some param + :return: the sum of the params + """ + + return par1 + + +def missing_type_doc(par1) -> int: # [missing-type-doc] + """This is a test docstring params where the type is not specified + + :param par1: some param + :return: the param + """ + + return par1 + + +def missing_type_doc_kwords_only(*, par1) -> int: # [missing-type-doc] + """This is a test docstring params where the type is not specified + + :param par1: some param + :return: the param + """ + + return par1 + + +def missing_type_doc_pos_only(par1, /) -> int: # [missing-type-doc] + """This is a test docstring params where the type is not specified + + :param par1: some param + :return: the param + """ + + return par1 diff --git a/tests/functional/ext/docparams/docparams.txt b/tests/functional/ext/docparams/docparams.txt index c75a954414..39c81af49a 100644 --- a/tests/functional/ext/docparams/docparams.txt +++ b/tests/functional/ext/docparams/docparams.txt @@ -10,3 +10,9 @@ missing-yield-doc:29:0:29:30:_async_private_func2:Missing yield documentation:UN missing-yield-type-doc:29:0:29:30:_async_private_func2:Missing yield type documentation:UNDEFINED missing-raises-doc:34:0:34:30:_async_private_func3:"""Exception"" not documented as being raised":UNDEFINED missing-any-param-doc:39:0:39:28:async_public_func1:"Missing any documentation in ""async_public_func1""":UNDEFINED +differing-param-doc:44:0:44:23:differing_param_doc:"""param"" differing in parameter documentation":UNDEFINED +differing-param-doc:55:0:55:35:differing_param_doc_kwords_only:"""param"" differing in parameter documentation":UNDEFINED +differing-param-doc:66:0:66:32:differing_param_doc_pos_only:"""param"" differing in parameter documentation":UNDEFINED +missing-type-doc:77:0:77:20:missing_type_doc:"""par1"" missing in parameter type documentation":UNDEFINED +missing-type-doc:87:0:87:32:missing_type_doc_kwords_only:"""par1"" missing in parameter type documentation":UNDEFINED +missing-type-doc:97:0:97:29:missing_type_doc_pos_only:"""par1"" missing in parameter type documentation":UNDEFINED From 415af6deca139b3951605369de4a15bb4f318840 Mon Sep 17 00:00:00 2001 From: mpernigo Date: Wed, 22 Jun 2022 13:45:14 +0200 Subject: [PATCH 4/7] Move ad hoc tests for python 3.8 to their own functional test --- tests/functional/ext/docparams/docparams.py | 21 ------------------ tests/functional/ext/docparams/docparams.txt | 6 ++--- .../ext/docparams/docparams_py38.py | 22 +++++++++++++++++++ .../ext/docparams/docparams_py38.rc | 11 ++++++++++ .../ext/docparams/docparams_py38.txt | 2 ++ 5 files changed, 37 insertions(+), 25 deletions(-) create mode 100644 tests/functional/ext/docparams/docparams_py38.py create mode 100644 tests/functional/ext/docparams/docparams_py38.rc create mode 100644 tests/functional/ext/docparams/docparams_py38.txt diff --git a/tests/functional/ext/docparams/docparams.py b/tests/functional/ext/docparams/docparams.py index 6e14cba2ad..720889b623 100644 --- a/tests/functional/ext/docparams/docparams.py +++ b/tests/functional/ext/docparams/docparams.py @@ -63,17 +63,6 @@ def differing_param_doc_kwords_only(*, par1: int) -> int: # [differing-param-do return par1 -def differing_param_doc_pos_only(par1: int, /) -> int: # [differing-param-doc] - """This is a test docstring documenting one non-existing param - - :param par1: some param - :param param: some param - :return: the sum of the params - """ - - return par1 - - def missing_type_doc(par1) -> int: # [missing-type-doc] """This is a test docstring params where the type is not specified @@ -92,13 +81,3 @@ def missing_type_doc_kwords_only(*, par1) -> int: # [missing-type-doc] """ return par1 - - -def missing_type_doc_pos_only(par1, /) -> int: # [missing-type-doc] - """This is a test docstring params where the type is not specified - - :param par1: some param - :return: the param - """ - - return par1 diff --git a/tests/functional/ext/docparams/docparams.txt b/tests/functional/ext/docparams/docparams.txt index 39c81af49a..69baf08503 100644 --- a/tests/functional/ext/docparams/docparams.txt +++ b/tests/functional/ext/docparams/docparams.txt @@ -12,7 +12,5 @@ missing-raises-doc:34:0:34:30:_async_private_func3:"""Exception"" not documented missing-any-param-doc:39:0:39:28:async_public_func1:"Missing any documentation in ""async_public_func1""":UNDEFINED differing-param-doc:44:0:44:23:differing_param_doc:"""param"" differing in parameter documentation":UNDEFINED differing-param-doc:55:0:55:35:differing_param_doc_kwords_only:"""param"" differing in parameter documentation":UNDEFINED -differing-param-doc:66:0:66:32:differing_param_doc_pos_only:"""param"" differing in parameter documentation":UNDEFINED -missing-type-doc:77:0:77:20:missing_type_doc:"""par1"" missing in parameter type documentation":UNDEFINED -missing-type-doc:87:0:87:32:missing_type_doc_kwords_only:"""par1"" missing in parameter type documentation":UNDEFINED -missing-type-doc:97:0:97:29:missing_type_doc_pos_only:"""par1"" missing in parameter type documentation":UNDEFINED +missing-type-doc:66:0:66:20:missing_type_doc:"""par1"" missing in parameter type documentation":UNDEFINED +missing-type-doc:76:0:76:32:missing_type_doc_kwords_only:"""par1"" missing in parameter type documentation":UNDEFINED diff --git a/tests/functional/ext/docparams/docparams_py38.py b/tests/functional/ext/docparams/docparams_py38.py new file mode 100644 index 0000000000..315661dc35 --- /dev/null +++ b/tests/functional/ext/docparams/docparams_py38.py @@ -0,0 +1,22 @@ +"""Fixture for testing missing documentation in docparams.""" + + +def differing_param_doc_pos_only(par1: int, /) -> int: # [differing-param-doc] + """This is a test docstring documenting one non-existing param + + :param par1: some param + :param param: some param + :return: the sum of the params + """ + + return par1 + + +def missing_type_doc_pos_only(par1, /) -> int: # [missing-type-doc] + """This is a test docstring params where the type is not specified + + :param par1: some param + :return: the param + """ + + return par1 diff --git a/tests/functional/ext/docparams/docparams_py38.rc b/tests/functional/ext/docparams/docparams_py38.rc new file mode 100644 index 0000000000..8b1c245088 --- /dev/null +++ b/tests/functional/ext/docparams/docparams_py38.rc @@ -0,0 +1,11 @@ +[MAIN] +load-plugins = pylint.extensions.docparams + +[BASIC] +accept-no-param-doc = no +accept-no-raise-doc = no +accept-no-return-doc = no +accept-no-yields-doc = no + +[testoptions] +min_pyver=3.8 diff --git a/tests/functional/ext/docparams/docparams_py38.txt b/tests/functional/ext/docparams/docparams_py38.txt new file mode 100644 index 0000000000..96eaa445ad --- /dev/null +++ b/tests/functional/ext/docparams/docparams_py38.txt @@ -0,0 +1,2 @@ +differing-param-doc:4:0:4:32:differing_param_doc_pos_only:"""param"" differing in parameter documentation":UNDEFINED +missing-type-doc:15:0:15:29:missing_type_doc_pos_only:"""par1"" missing in parameter type documentation":UNDEFINED From 31cc256e18b41463a22ad4e2e14f6fbb3760bb0f Mon Sep 17 00:00:00 2001 From: mpernigo Date: Wed, 22 Jun 2022 13:57:38 +0200 Subject: [PATCH 5/7] Extend docstring on `docparams` tests --- tests/functional/ext/docparams/docparams_py38.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/functional/ext/docparams/docparams_py38.py b/tests/functional/ext/docparams/docparams_py38.py index 315661dc35..989001322b 100644 --- a/tests/functional/ext/docparams/docparams_py38.py +++ b/tests/functional/ext/docparams/docparams_py38.py @@ -1,4 +1,4 @@ -"""Fixture for testing missing documentation in docparams.""" +"""Fixture for testing missing documentation in docparams (Python >=3.8 only).""" def differing_param_doc_pos_only(par1: int, /) -> int: # [differing-param-doc] From 3b41b465d998d74fc6ed93a1292021feb7a464eb Mon Sep 17 00:00:00 2001 From: mpernigo Date: Thu, 23 Jun 2022 08:27:03 +0200 Subject: [PATCH 6/7] Add tests to cover cases where it's all documented --- tests/functional/ext/docparams/docparams.py | 11 +++++++++++ tests/functional/ext/docparams/docparams_py38.py | 12 ++++++++++++ 2 files changed, 23 insertions(+) diff --git a/tests/functional/ext/docparams/docparams.py b/tests/functional/ext/docparams/docparams.py index 720889b623..295cf430d6 100644 --- a/tests/functional/ext/docparams/docparams.py +++ b/tests/functional/ext/docparams/docparams.py @@ -81,3 +81,14 @@ def missing_type_doc_kwords_only(*, par1) -> int: # [missing-type-doc] """ return par1 + + +def params_are_documented(par1: int, *, par2: int) -> int: + """This is a test docstring params where nothing is raised as it is all documented + + :param par1: some param + :param par2: some other param + :return: the sum of params + """ + + return par1 + par2 diff --git a/tests/functional/ext/docparams/docparams_py38.py b/tests/functional/ext/docparams/docparams_py38.py index 989001322b..7044fb369d 100644 --- a/tests/functional/ext/docparams/docparams_py38.py +++ b/tests/functional/ext/docparams/docparams_py38.py @@ -20,3 +20,15 @@ def missing_type_doc_pos_only(par1, /) -> int: # [missing-type-doc] """ return par1 + + +def params_are_documented(par1: int, /, par2: int, *, par3: int) -> int: + """This is a test docstring params where nothing is raised as it is all documented + + :param par1: some param + :param par2: some other param + :param par3: some other param + :return: the sum of params + """ + + return par1 + par2 + par3 From 26d76b2992f3e0d3820c55e5045fb884c65394b5 Mon Sep 17 00:00:00 2001 From: Pierre Sassoulas Date: Thu, 23 Jun 2022 09:04:15 +0200 Subject: [PATCH 7/7] Update doc/whatsnew/2/2.15/index.rst --- doc/whatsnew/2/2.15/index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/whatsnew/2/2.15/index.rst b/doc/whatsnew/2/2.15/index.rst index 4d3d135c69..2226f88669 100644 --- a/doc/whatsnew/2/2.15/index.rst +++ b/doc/whatsnew/2/2.15/index.rst @@ -39,7 +39,6 @@ False positives fixed Closes #4951 - False negatives fixed =====================