Move some of the Numpy tests out of ``TestParamDocChecker`` (#5492)

5 files changed, 481 insertions, 4 deletions

diff --git a/tests/functional/ext/docparams/parameter/missing_param_doc_required_Numpy.py b/tests/functional/ext/docparams/parameter/missing_param_doc_required_Numpy.py
new file mode 100644
index 000000000..e780ac0f5
--- /dev/null
+++ b/tests/functional/ext/docparams/parameter/missing_param_doc_required_Numpy.py
@@ -0,0 +1,374 @@
+"""Tests for missing-param-doc and missing-type-doc for Numpy style docstrings
+with accept-no-param-doc = no
+"""
+# pylint: disable=invalid-name, unused-argument, undefined-variable, too-many-arguments
+# pylint: disable=line-too-long, too-few-public-methods, missing-class-docstring
+# pylint: disable=missing-function-docstring, function-redefined, inconsistent-return-statements
+
+
+def test_missing_func_params_in_numpy_docstring(  # [missing-param-doc, missing-type-doc]
+    x, y, z
+):
+    """Example of a function with missing NumPy style parameter
+        documentation in the docstring
+
+    Parameters
+    ----------
+    x:
+        bla
+    z: int
+        bar
+
+    some other stuff
+    """
+
+
+class Foo:
+    def test_missing_method_params_in_numpy_docstring(  # [missing-param-doc, missing-type-doc]
+        self, x, y
+    ):
+        """Example of a class method with missing parameter documentation in
+        the Numpy style docstring
+
+        missing parameter documentation
+
+        Parameters
+        ----------
+        x:
+            bla
+        """
+
+
+def test_existing_func_params_in_numpy_docstring(xarg, yarg, zarg, warg):
+    """Example of a function with correctly documented parameters and
+    return values (Numpy style)
+
+    Parameters
+    ----------
+    xarg: int
+        bla xarg
+    yarg: my.qualified.type
+        bla yarg
+
+    zarg: int
+        bla zarg
+    warg: my.qualified.type
+        bla warg
+
+    Returns
+    -------
+    float
+        sum
+    """
+    return xarg + yarg
+
+
+def test_wrong_name_of_func_params_in_numpy_docstring(  # [missing-param-doc, missing-type-doc, differing-param-doc, differing-type-doc]
+    xarg, yarg, zarg
+):
+    """Example of functions with inconsistent parameter names in the
+    signature and in the Numpy style documentation
+
+    Parameters
+    ----------
+    xarg1: int
+        bla xarg
+    yarg: float
+        bla yarg
+
+    zarg1: str
+        bla zarg
+    """
+    return xarg + yarg
+
+
+def test_wrong_name_of_func_params_in_numpy_docstring_two(  # [differing-param-doc, differing-type-doc]
+    xarg, yarg
+):
+    """Example of functions with inconsistent parameter names in the
+    signature and in the Numpy style documentation
+
+    Parameters
+    ----------
+    yarg1: float
+        bla yarg
+
+    For the other parameters, see bla.
+    """
+    return xarg + yarg
+
+
+def test_see_sentence_for_func_params_in_numpy_docstring(xarg, yarg):
+    """Example for the usage of "For the other parameters, see" to avoid
+    too many repetitions, e.g. in functions or methods adhering to a
+    given interface (Numpy style)
+
+    Parameters
+    ----------
+    yarg: float
+        bla yarg
+
+    For the other parameters, see :func:`bla`
+    """
+    return xarg + yarg
+
+
+class ClassFoo:  # [missing-param-doc, missing-type-doc]
+    """test_constr_params_in_class_numpy
+    Example of a class with missing constructor parameter documentation
+    (Numpy style)
+
+    Everything is completely analogous to functions.
+
+    Parameters
+    ----------
+    y:
+        bla
+
+    missing constructor parameter documentation
+    """
+
+    def __init__(self, x, y):
+        pass
+
+
+class ClassFoo:
+    """test_constr_params_and_attributes_in_class_numpy
+    Example of a class with correct constructor parameter documentation
+    and an attributes section (Numpy style)
+
+    Parameters
+    ----------
+    foobar : str
+        Something.
+
+    Attributes
+    ----------
+    barfoor : str
+        Something.
+    """
+
+    def __init__(self, foobar):
+        self.barfoo = None
+
+
+class ClassFoo:
+    def __init__(self, x, y):  # [missing-param-doc, missing-type-doc]
+        """test_constr_params_in_init_numpy
+        Example of a class with missing constructor parameter documentation
+        (Numpy style)
+
+        Everything is completely analogous to functions.
+
+        Parameters
+        ----------
+        y:
+            bla
+
+        missing constructor parameter documentation
+        """
+
+
+class ClassFoo:  # [multiple-constructor-doc, missing-param-doc, missing-type-doc]
+    """test_constr_params_in_class_and_init_numpy
+    Example of a class with missing constructor parameter documentation
+    in both the init docstring and the class docstring
+    (Numpy style)
+
+    Everything is completely analogous to functions.
+
+    Parameters
+    ----------
+    y:
+        bla
+
+    missing constructor parameter documentation
+    """
+
+    def __init__(self, x, y):  # [missing-param-doc, missing-type-doc]
+        """docstring foo
+
+        Parameters
+        ----------
+        y:
+            bla
+
+        missing constructor parameter documentation
+        """
+
+
+def test_warns_missing_args_numpy(named_arg, *args):  # [missing-param-doc]
+    """The docstring
+
+    Args
+    ----
+    named_arg : object
+        Returned
+
+    Returns
+    -------
+        object or None
+            Maybe named_arg
+    """
+    if args:
+        return named_arg
+
+
+def test_warns_missing_kwargs_numpy(named_arg, **kwargs):  # [missing-param-doc]
+    """The docstring
+
+    Args
+    ----
+    named_arg : object
+        Returned
+
+    Returns
+    -------
+        object or None
+            Maybe named_arg
+    """
+    if kwargs:
+        return named_arg
+
+
+def test_finds_args_without_type_numpy(  # [missing-type-doc]
+    named_arg, typed_arg: bool, untyped_arg, *args
+):
+    """The docstring
+
+    Args
+    ----
+    named_arg : object
+        Returned
+    typed_arg
+        Other argument without numpy type annotation
+    untyped_arg
+        Other argument without any type annotation
+    *args :
+        Optional Arguments
+
+    Returns
+    -------
+        object or None
+            Maybe named_arg
+    """
+    if args:
+        return named_arg
+
+
+def test_finds_args_with_xref_type_numpy(named_arg, *args):
+    """The docstring
+
+    Args
+    ----
+    named_arg : `example.value`
+        Returned
+    *args :
+        Optional Arguments
+
+    Returns
+    -------
+        `example.value`
+            Maybe named_arg
+    """
+    if args:
+        return named_arg
+
+
+def test_finds_kwargs_without_type_numpy(named_arg, **kwargs):
+    """The docstring
+
+    Args
+    ----
+    named_arg : object
+        Returned
+    **kwargs :
+        Keyword arguments
+
+    Returns
+    -------
+        object or None
+            Maybe named_arg
+    """
+    if kwargs:
+        return named_arg
+
+
+def my_func(
+    named_arg_one,
+    named_arg_two,
+    named_arg_three,
+    named_arg_four,
+    named_arg_five,
+    named_arg_six,
+    named_arg_seven,
+    named_arg_eight,
+):
+    """The docstring
+
+    Args
+    ----
+    named_arg_one : dict(str,str)
+        Returned
+    named_arg_two : dict[str,str]
+        Returned
+    named_arg_three : tuple(int)
+        Returned
+    named_arg_four : list[tokenize.TokenInfo]
+        Returned
+    named_arg_five : int or str
+        Returned
+    named_arg_six : tuple(int or str)
+        Returned
+    named_arg_seven : tuple(int) or list(int)
+        Returned
+    named_arg_eight : tuple(int or str) or list(int or str)
+        Returned
+
+    Returns
+    -------
+        dict(str,str)
+            named_arg_one
+        dict[str,str]
+            named_arg_two
+        tuple(int)
+            named_arg_three
+        list[tokenize.TokenInfo]
+            named_arg_four
+        int or str
+            named_arg_five
+        tuple(int or str)
+            named_arg_six
+        tuple(int) or list(int)
+            named_arg_seven
+        tuple(int or str) or list(int or str)
+            named_arg_eight
+    """
+    return (
+        named_arg_one,
+        named_arg_two,
+        named_arg_three,
+        named_arg_four,
+        named_arg_five,
+        named_arg_six,
+        named_arg_seven,
+        named_arg_eight,
+    )
+
+
+def test_ignores_optional_specifier_numpy(param, param2="all"):
+    """Do something.
+
+    Parameters
+    ----------
+    param : str
+        Description.
+    param2 : str, optional
+        Description (the default is 'all').
+
+    Returns
+    -------
+    int
+        Description.
+    """
+    return param, param2
diff --git a/tests/functional/ext/docparams/parameter/missing_param_doc_required_Numpy.rc b/tests/functional/ext/docparams/parameter/missing_param_doc_required_Numpy.rc
new file mode 100644
index 000000000..24cdf9ada
--- /dev/null
+++ b/tests/functional/ext/docparams/parameter/missing_param_doc_required_Numpy.rc
@@ -0,0 +1,7 @@
+[MASTER]
+load-plugins = pylint.extensions.docparams
+
+[BASIC]
+accept-no-param-doc=no
+docstring-min-length: -1
+no-docstring-rgx=^$
diff --git a/tests/functional/ext/docparams/parameter/missing_param_doc_required_Numpy.txt b/tests/functional/ext/docparams/parameter/missing_param_doc_required_Numpy.txt
new file mode 100644
index 000000000..d4f8be211
--- /dev/null
+++ b/tests/functional/ext/docparams/parameter/missing_param_doc_required_Numpy.txt
@@ -0,0 +1,22 @@
+missing-param-doc:9:0:23:7:test_missing_func_params_in_numpy_docstring:"""y"" missing in parameter documentation":UNDEFINED
+missing-type-doc:9:0:23:7:test_missing_func_params_in_numpy_docstring:"""x, y"" missing in parameter type documentation":UNDEFINED
+missing-param-doc:27:4:39:11:Foo.test_missing_method_params_in_numpy_docstring:"""y"" missing in parameter documentation":UNDEFINED
+missing-type-doc:27:4:39:11:Foo.test_missing_method_params_in_numpy_docstring:"""x, y"" missing in parameter type documentation":UNDEFINED
+differing-param-doc:66:0:82:22:test_wrong_name_of_func_params_in_numpy_docstring:"""xarg1, zarg1"" differing in parameter documentation":UNDEFINED
+differing-type-doc:66:0:82:22:test_wrong_name_of_func_params_in_numpy_docstring:"""xarg1, zarg1"" differing in parameter type documentation":UNDEFINED
+missing-param-doc:66:0:82:22:test_wrong_name_of_func_params_in_numpy_docstring:"""xarg, zarg"" missing in parameter documentation":UNDEFINED
+missing-type-doc:66:0:82:22:test_wrong_name_of_func_params_in_numpy_docstring:"""xarg, zarg"" missing in parameter type documentation":UNDEFINED
+differing-param-doc:85:0:98:22:test_wrong_name_of_func_params_in_numpy_docstring_two:"""yarg1"" differing in parameter documentation":UNDEFINED
+differing-type-doc:85:0:98:22:test_wrong_name_of_func_params_in_numpy_docstring_two:"""yarg1"" differing in parameter type documentation":UNDEFINED
+missing-param-doc:116:0:132:12:ClassFoo:"""x"" missing in parameter documentation":UNDEFINED
+missing-type-doc:116:0:132:12:ClassFoo:"""x, y"" missing in parameter type documentation":UNDEFINED
+missing-param-doc:156:4:169:11:ClassFoo.__init__:"""x"" missing in parameter documentation":UNDEFINED
+missing-type-doc:156:4:169:11:ClassFoo.__init__:"""x, y"" missing in parameter type documentation":UNDEFINED
+missing-param-doc:172:0:197:11:ClassFoo:"""x"" missing in parameter documentation":UNDEFINED
+missing-type-doc:172:0:197:11:ClassFoo:"""x, y"" missing in parameter type documentation":UNDEFINED
+multiple-constructor-doc:172:0:197:11:ClassFoo:"""ClassFoo"" has constructor parameters documented in class and __init__":UNDEFINED
+missing-param-doc:188:4:197:11:ClassFoo.__init__:"""x"" missing in parameter documentation":UNDEFINED
+missing-type-doc:188:4:197:11:ClassFoo.__init__:"""x, y"" missing in parameter type documentation":UNDEFINED
+missing-param-doc:200:0:214:24:test_warns_missing_args_numpy:"""*args"" missing in parameter documentation":UNDEFINED
+missing-param-doc:217:0:231:24:test_warns_missing_kwargs_numpy:"""**kwargs"" missing in parameter documentation":UNDEFINED
+missing-type-doc:234:0:256:24:test_finds_args_without_type_numpy:"""untyped_arg"" missing in parameter type documentation":UNDEFINED
diff --git a/tests/functional/ext/docparams/return/missing_return_doc_Numpy.py b/tests/functional/ext/docparams/return/missing_return_doc_Numpy.py
index 269adb424..47f6f4ae0 100644
--- a/tests/functional/ext/docparams/return/missing_return_doc_Numpy.py
+++ b/tests/functional/ext/docparams/return/missing_return_doc_Numpy.py
@@ -1,6 +1,7 @@
 """Tests for missing-return-doc and missing-return-type-doc for Numpy style docstrings"""
 # pylint: disable=function-redefined, invalid-name, undefined-variable, missing-function-docstring
-# pylint: disable=unused-argument
+# pylint: disable=unused-argument, too-few-public-methods, disallowed-name
+import abc
 
 
 def my_func(self):
@@ -103,3 +104,74 @@ def my_func(self):  # [redundant-returns-doc]
             One
     """
     yield 1
+
+
+class Foo:
+    """test_ignores_return_in_abstract_method_numpy
+    Example of an abstract method documenting the return type that an
+    implementation should return."""
+
+    @abc.abstractmethod
+    def foo(self):
+        """docstring ...
+
+        Returns
+        -------
+        int
+            Ten
+        """
+        return 10
+
+
+class Foo:
+    """test_ignores_return_in_abstract_method_numpy_2
+    Example of a method documenting the return type that an
+    implementation should return."""
+
+    def foo(self, arg):
+        """docstring ...
+
+        Parameters
+        ----------
+        arg : int
+            An argument.
+        """
+        raise NotImplementedError()
+
+
+class Foo:
+    """test_ignores_ignored_argument_names_numpy
+    Example of a method documenting the return type that an
+    implementation should return.
+    """
+
+    def foo(self, arg, _):
+        """docstring ...
+
+        Parameters
+        ----------
+        arg : int
+            An argument.
+        """
+
+
+class Foo:
+    """test_useless_docs_ignored_argument_names_numpy
+    Example of a method documenting the return type that an
+    implementation should return.
+    """
+
+    def foo(self, arg, _, _ignored):  # [useless-type-doc, useless-param-doc]
+        """docstring ...
+
+        Parameters
+        ----------
+        arg : int
+            An argument.
+
+        _ : float
+            Another argument.
+
+        _ignored :
+            Ignored Argument
+        """
diff --git a/tests/functional/ext/docparams/return/missing_return_doc_Numpy.txt b/tests/functional/ext/docparams/return/missing_return_doc_Numpy.txt
index 1c17a80af..d137612e6 100644
--- a/tests/functional/ext/docparams/return/missing_return_doc_Numpy.txt
+++ b/tests/functional/ext/docparams/return/missing_return_doc_Numpy.txt
@@ -1,3 +1,5 @@
-redundant-returns-doc:61:0:69:15:my_func:Redundant returns documentation:UNDEFINED
-redundant-returns-doc:72:0:79:15:my_func:Redundant returns documentation:UNDEFINED
-redundant-returns-doc:97:0:105:11:my_func:Redundant returns documentation:UNDEFINED
+redundant-returns-doc:62:0:70:15:my_func:Redundant returns documentation:UNDEFINED
+redundant-returns-doc:73:0:80:15:my_func:Redundant returns documentation:UNDEFINED
+redundant-returns-doc:98:0:106:11:my_func:Redundant returns documentation:UNDEFINED
+useless-param-doc:164:4:177:11:Foo.foo:"""_, _ignored"" useless ignored parameter documentation":UNDEFINED
+useless-type-doc:164:4:177:11:Foo.foo:"""_"" useless ignored parameter type documentation":UNDEFINED