Fix differing param doc false positive (#6980)

* Read `posonly` args and annotations on `check_arguments_in_docstring`

Co-authored-by: Pierre Sassoulas <[email protected]>

doc/whatsnew/2/2.14/full.rst

@@ -5,6 +5,9 @@ What's New in Pylint 2.14.4?
 ----------------------------
 Release date: TBA
 
+* The ``differing-param-doc`` check was triggered by positional only arguments.
+
+  Closes #6950
 
 
 What's New in Pylint 2.14.3?

pylint/extensions/docparams.py

@@ -524,6 +524,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()
@@ -561,6 +562,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) - (

tests/functional/ext/docparams/docparams.py

@@ -39,3 +39,56 @@ 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 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 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

tests/functional/ext/docparams/docparams.txt

@@ -10,3 +10,7 @@ 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
+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

tests/functional/ext/docparams/docparams_py38.py

@@ -0,0 +1,34 @@
+"""Fixture for testing missing documentation in docparams (Python >=3.8 only)."""
+
+
+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
+
+
+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

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

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