From be1c655311d908b1fc02b61423e98e0f7257f688 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Noord?= <13665637+DanielNoord@users.noreply.github.com> Date: Wed, 1 Dec 2021 16:56:07 +0100 Subject: [PATCH] Move Sphinx docstrings out of ``TestParamDocChecker`` --- tests/extensions/test_check_docs.py | 588 ------------------ .../missing_param_doc_required_Sphinx.py | 418 +++++++++++++ .../missing_param_doc_required_Sphinx.rc | 7 + .../missing_param_doc_required_Sphinx.txt | 33 + .../raise/missing_raises_doc_Sphinx.py | 11 + .../raise/missing_raises_doc_Sphinx.txt | 26 +- .../return/missing_return_doc_Sphinx.py | 32 +- .../return/missing_return_doc_Sphinx.txt | 4 +- .../missing_return_doc_required_Sphinx.py | 38 +- .../missing_return_doc_required_Sphinx.txt | 14 +- 10 files changed, 560 insertions(+), 611 deletions(-) create mode 100644 tests/functional/ext/docparams/parameter/missing_param_doc_required_Sphinx.py create mode 100644 tests/functional/ext/docparams/parameter/missing_param_doc_required_Sphinx.rc create mode 100644 tests/functional/ext/docparams/parameter/missing_param_doc_required_Sphinx.txt diff --git a/tests/extensions/test_check_docs.py b/tests/extensions/test_check_docs.py index 58c2dccc68..0f7f6c252b 100644 --- a/tests/extensions/test_check_docs.py +++ b/tests/extensions/test_check_docs.py @@ -48,28 +48,6 @@ class TestParamDocChecker(CheckerTestCase): "docstring_min_length": -1, } - def test_missing_func_params_in_sphinx_docstring(self) -> None: - """Example of a function with missing Sphinx parameter documentation in - the docstring - """ - node = astroid.extract_node( - """ - def function_foo(x, y, z): - '''docstring ... - - :param x: bla - - :param int z: bar - ''' - pass - """ - ) - with self.assertAddsMessages( - MessageTest(msg_id="missing-param-doc", node=node, args=("y",)), - MessageTest(msg_id="missing-type-doc", node=node, args=("x, y",)), - ): - self.checker.visit_functiondef(node) - def test_missing_func_params_in_google_docstring(self) -> None: """Example of a function with missing Google style parameter documentation in the docstring @@ -358,30 +336,6 @@ def _visit_methods_of_class(self, node: nodes.ClassDef) -> None: if isinstance(body_item, nodes.FunctionDef) and hasattr(body_item, "name"): self.checker.visit_functiondef(body_item) - def test_missing_method_params_in_sphinx_docstring(self) -> None: - """Example of a class method with missing parameter documentation in - the Sphinx style docstring - """ - node = astroid.extract_node( - """ - class Foo(object): - def method_foo(self, x, y): - '''docstring ... - - missing parameter documentation - - :param x: bla - ''' - pass - """ - ) - method_node = node.body[0] - with self.assertAddsMessages( - MessageTest(msg_id="missing-param-doc", node=method_node, args=("y",)), - MessageTest(msg_id="missing-type-doc", node=method_node, args=("x, y",)), - ): - self._visit_methods_of_class(node) - def test_missing_method_params_in_google_docstring(self) -> None: """Example of a class method with missing parameter documentation in the Google style docstring @@ -434,34 +388,6 @@ def method_foo(self, x, y): ): self._visit_methods_of_class(node) - def test_existing_func_params_in_sphinx_docstring(self) -> None: - """Example of a function with correctly documented parameters and - return values (Sphinx style) - """ - node = astroid.extract_node( - """ - def function_foo(xarg, yarg, zarg, warg): - '''function foo ... - - :param xarg: bla xarg - :type xarg: int - - :parameter yarg: bla yarg - :type yarg: my.qualified.type - - :arg int zarg: bla zarg - - :keyword my.qualified.type warg: bla warg - - :return: sum - :rtype: float - ''' - return xarg + yarg - """ - ) - with self.assertNoMessages(): - self.checker.visit_functiondef(node) - def test_existing_func_params_in_google_docstring(self) -> None: """Example of a function with correctly documented parameters and return values (Google style) @@ -520,55 +446,6 @@ def function_foo(xarg, yarg, zarg, warg): with self.assertNoMessages(): self.checker.visit_functiondef(node) - def test_wrong_name_of_func_params_in_sphinx_docstring(self) -> None: - """Example of functions with inconsistent parameter names in the - signature and in the Sphinx style documentation - """ - node = astroid.extract_node( - """ - def function_foo(xarg, yarg, zarg): - '''function foo ... - - :param xarg1: bla xarg - :type xarg: int - - :param yarg: bla yarg - :type yarg1: float - - :param str zarg1: bla zarg - ''' - return xarg + yarg - """ - ) - with self.assertAddsMessages( - MessageTest(msg_id="missing-param-doc", node=node, args=("xarg, zarg",)), - MessageTest(msg_id="missing-type-doc", node=node, args=("yarg, zarg",)), - MessageTest( - msg_id="differing-param-doc", node=node, args=("xarg1, zarg1",) - ), - MessageTest(msg_id="differing-type-doc", node=node, args=("yarg1, zarg1",)), - ): - self.checker.visit_functiondef(node) - - node = astroid.extract_node( - """ - def function_foo(xarg, yarg): - '''function foo ... - - :param yarg1: bla yarg - :type yarg1: float - - For the other parameters, see bla. - ''' - return xarg + yarg - """ - ) - with self.assertAddsMessages( - MessageTest(msg_id="differing-param-doc", node=node, args=("yarg1",)), - MessageTest(msg_id="differing-type-doc", node=node, args=("yarg1",)), - ): - self.checker.visit_functiondef(node) - def test_wrong_name_of_func_params_in_google_docstring(self) -> None: """Example of functions with inconsistent parameter names in the signature and in the Google style documentation @@ -669,27 +546,6 @@ def function_foo(xarg, yarg): ): self.checker.visit_functiondef(node) - def test_see_sentence_for_func_params_in_sphinx_docstring(self) -> None: - """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 (Sphinx style) - """ - node = astroid.extract_node( - """ - def function_foo(xarg, yarg): - '''function foo ... - - :param yarg: bla yarg - :type yarg: float - - For the other parameters, see :func:`bla` - ''' - return xarg + yarg - """ - ) - with self.assertNoMessages(): - self.checker.visit_functiondef(node) - def test_see_sentence_for_func_params_in_google_docstring(self) -> None: """Example for the usage of "For the other parameters, see" to avoid too many repetitions, e.g. in functions or methods adhering to a @@ -734,33 +590,6 @@ def function_foo(xarg, yarg): with self.assertNoMessages(): self.checker.visit_functiondef(node) - def test_constr_params_in_class_sphinx(self) -> None: - """Example of a class with missing constructor parameter documentation - (Sphinx style) - - Everything is completely analogous to functions. - """ - node = astroid.extract_node( - """ - class ClassFoo(object): - '''docstring foo - - :param y: bla - - missing constructor parameter documentation - ''' - - def __init__(self, x, y): - pass - - """ - ) - with self.assertAddsMessages( - MessageTest(msg_id="missing-param-doc", node=node, args=("x",)), - MessageTest(msg_id="missing-type-doc", node=node, args=("x, y",)), - ): - self._visit_methods_of_class(node) - def test_constr_params_in_class_google(self) -> None: """Example of a class with missing constructor parameter documentation (Google style) @@ -844,36 +673,6 @@ def __init__(self, foo): with self.assertNoMessages(): self._visit_methods_of_class(node) - def test_constr_params_in_init_sphinx(self) -> None: - """Example of a class with missing constructor parameter documentation - (Sphinx style) - - Everything is completely analogous to functions. - """ - node = astroid.extract_node( - """ - class ClassFoo(object): - def __init__(self, x, y): - '''docstring foo constructor - - :param y: bla - - missing constructor parameter documentation - ''' - - pass - - """ - ) - constructor_node = node.body[0] - with self.assertAddsMessages( - MessageTest(msg_id="missing-param-doc", node=constructor_node, args=("x",)), - MessageTest( - msg_id="missing-type-doc", node=constructor_node, args=("x, y",) - ), - ): - self._visit_methods_of_class(node) - def test_constr_params_in_init_google(self) -> None: """Example of a class with missing constructor parameter documentation (Google style) @@ -974,48 +773,6 @@ def __init__(self, x, y): with self.assertNoMessages(): self._visit_methods_of_class(node) - def test_constr_params_in_class_and_init_sphinx(self) -> None: - """Example of a class with missing constructor parameter documentation - in both the init docstring and the class docstring - (Sphinx style) - - Everything is completely analogous to functions. - """ - node = astroid.extract_node( - """ - class ClassFoo(object): - '''docstring foo - - :param y: None - - missing constructor parameter documentation - ''' - - def __init__(self, x, y): - '''docstring foo - - :param y: bla - - missing constructor parameter documentation - ''' - pass - - """ - ) - constructor_node = node.body[0] - with self.assertAddsMessages( - MessageTest( - msg_id="multiple-constructor-doc", node=node, args=(node.name,) - ), - MessageTest(msg_id="missing-param-doc", node=node, args=("x",)), - MessageTest(msg_id="missing-type-doc", node=node, args=("x, y",)), - MessageTest(msg_id="missing-param-doc", node=constructor_node, args=("x",)), - MessageTest( - msg_id="missing-type-doc", node=constructor_node, args=("x, y",) - ), - ): - self._visit_methods_of_class(node) - def test_constr_params_in_class_and_init_google(self) -> None: """Example of a class with missing constructor parameter documentation in both the init docstring and the class docstring @@ -1127,46 +884,6 @@ def my_func(arg, *, kwonly, missing_kwonly): ): self.checker.visit_functiondef(node) - def test_warns_missing_args_sphinx(self) -> None: - node = astroid.extract_node( - ''' - def my_func(named_arg, *args): - """The docstring - - :param named_arg: Returned - :type named_arg: object - :returns: Maybe named_arg - :rtype: object or None - """ - if args: - return named_arg - ''' - ) - with self.assertAddsMessages( - MessageTest(msg_id="missing-param-doc", node=node, args=("*args",)) - ): - self.checker.visit_functiondef(node) - - def test_warns_missing_kwargs_sphinx(self) -> None: - node = astroid.extract_node( - ''' - def my_func(named_arg, **kwargs): - """The docstring - - :param named_arg: Returned - :type named_arg: object - :returns: Maybe named_arg - :rtype: object or None - """ - if kwargs: - return named_arg - ''' - ) - with self.assertAddsMessages( - MessageTest(msg_id="missing-param-doc", node=node, args=("**kwargs",)) - ): - self.checker.visit_functiondef(node) - def test_warns_missing_args_google(self) -> None: node = astroid.extract_node( ''' @@ -1259,44 +976,6 @@ def my_func(named_arg, **kwargs): ): self.checker.visit_functiondef(node) - def test_finds_args_without_type_sphinx(self) -> None: - node = astroid.extract_node( - ''' - def my_func(named_arg, *args): - """The docstring - - :param named_arg: Returned - :type named_arg: object - :param *args: Optional arguments - :returns: Maybe named_arg - :rtype: object or None - """ - if args: - return named_arg - ''' - ) - with self.assertNoMessages(): - self.checker.visit_functiondef(node) - - def test_finds_kwargs_without_type_sphinx(self) -> None: - node = astroid.extract_node( - ''' - def my_func(named_arg, **kwargs): - """The docstring - - :param named_arg: Returned - :type named_arg: object - :param **kwargs: Keyword arguments - :returns: Maybe named_arg - :rtype: object or None - """ - if kwargs: - return named_arg - ''' - ) - with self.assertNoMessages(): - self.checker.visit_functiondef(node) - def test_finds_args_without_type_google(self) -> None: node = astroid.extract_node( ''' @@ -1454,25 +1133,6 @@ def my_func(named_arg, **kwargs): "tuple(int or str) or list(int or str)", ] - @pytest.mark.parametrize("complex_type", COMPLEX_TYPES) - def test_finds_multiple_types_sphinx(self, complex_type): - node = astroid.extract_node( - f''' - def my_func(named_arg): - """The docstring - - :param named_arg: Returned - :type named_arg: {complex_type} - - :returns: named_arg - :rtype: {complex_type} - """ - return named_arg - ''' - ) - with self.assertNoMessages(): - self.checker.visit_functiondef(node) - @pytest.mark.parametrize("complex_type", COMPLEX_TYPES) def test_finds_multiple_types_google(self, complex_type): node = astroid.extract_node( @@ -1515,24 +1175,6 @@ def my_func(named_arg): with self.assertNoMessages(): self.checker.visit_functiondef(node) - @pytest.mark.parametrize("container_type", CONTAINER_TYPES) - def test_finds_compact_container_types_sphinx(self, container_type): - node = astroid.extract_node( - f''' - def my_func(named_arg): - """The docstring - - :param {container_type} named_arg: Returned - - :returns: named_arg - :rtype: {container_type} - """ - return named_arg - ''' - ) - with self.assertNoMessages(): - self.checker.visit_functiondef(node) - def test_ignores_optional_specifier_google(self) -> None: node = astroid.extract_node( ''' @@ -1597,35 +1239,6 @@ def do_something(): #@ with self.assertNoMessages(): self.checker.visit_functiondef(node) - def test_finds_missing_raises_from_setter_sphinx(self) -> None: - """Example of a setter having missing raises documentation in - the Sphinx style docstring of the property - """ - property_node, node = astroid.extract_node( - """ - class Foo(object): - @property - def foo(self): #@ - '''docstring ... - - :type: int - ''' - return 10 - - @foo.setter - def foo(self, value): - raise AttributeError() #@ - """ - ) - with self.assertAddsMessages( - MessageTest( - msg_id="missing-raises-doc", - node=property_node, - args=("AttributeError",), - ) - ): - self.checker.visit_raise(node) - def test_finds_missing_raises_from_setter_google(self) -> None: """Example of a setter having missing raises documentation in the Google style docstring of the property @@ -1696,39 +1309,6 @@ def foo(self, value): ): self.checker.visit_raise(node) - def test_finds_missing_raises_in_setter_sphinx(self) -> None: - """Example of a setter having missing raises documentation in - its own Sphinx style docstring - """ - setter_node, node = astroid.extract_node( - """ - class Foo(object): - @property - def foo(self): - '''docstring ... - - :type: int - :raises RuntimeError: Always - ''' - raise RuntimeError() - return 10 - - @foo.setter - def foo(self, value): #@ - '''setter docstring ... - - :type: None - ''' - raise AttributeError() #@ - """ - ) - with self.assertAddsMessages( - MessageTest( - msg_id="missing-raises-doc", node=setter_node, args=("AttributeError",) - ) - ): - self.checker.visit_raise(node) - def test_finds_missing_raises_from_setter_google_2(self) -> None: """Example of a setter having missing raises documentation in its own Google style docstring of the property @@ -1805,25 +1385,6 @@ def foo(self, value): #@ ): self.checker.visit_raise(node) - def test_finds_property_return_type_sphinx(self) -> None: - """Example of a property having return documentation in - a Sphinx style docstring - """ - node = astroid.extract_node( - """ - class Foo(object): - @property - def foo(self): #@ - '''docstring ... - - :type: int - ''' - return 10 - """ - ) - with self.assertNoMessages(): - self.checker.visit_functiondef(node) - def test_finds_property_return_type_google(self) -> None: """Example of a property having return documentation in a Google style docstring @@ -1868,49 +1429,6 @@ def foo(self): #@ with self.assertNoMessages(): self.checker.visit_functiondef(node) - def test_finds_annotation_property_return_type_sphinx(self) -> None: - """Example of a property having missing return documentation in - a Sphinx style docstring - """ - _, node = astroid.extract_node( - """ - class Foo(object): - @property - def foo(self) -> int: #@ - '''docstring ... - - :raises RuntimeError: Always - ''' - raise RuntimeError() - return 10 #@ - """ - ) - with self.assertNoMessages(): - self.checker.visit_return(node) - - @set_config(accept_no_return_doc="no") - def test_finds_missing_property_return_type_sphinx(self) -> None: - """Example of a property having missing return documentation in - a Sphinx style docstring - """ - property_node, node = astroid.extract_node( - """ - class Foo(object): - @property - def foo(self): #@ - '''docstring ... - - :raises RuntimeError: Always - ''' - raise RuntimeError() - return 10 #@ - """ - ) - with self.assertAddsMessages( - MessageTest(msg_id="missing-return-type-doc", node=property_node) - ): - self.checker.visit_return(node) - def test_finds_annotation_property_return_type_google(self) -> None: """Example of a property having return documentation in a Google style docstring @@ -1982,28 +1500,6 @@ def foo(self): #@ ): self.checker.visit_return(node) - @set_config(accept_no_return_doc="no") - def test_ignores_non_property_return_type_sphinx(self) -> None: - """Example of a class function trying to use `type` as return - documentation in a Sphinx style docstring - """ - func_node, node = astroid.extract_node( - """ - class Foo(object): - def foo(self): #@ - '''docstring ... - - :type: int - ''' - return 10 #@ - """ - ) - with self.assertAddsMessages( - MessageTest(msg_id="missing-return-doc", node=func_node), - MessageTest(msg_id="missing-return-type-doc", node=func_node), - ): - self.checker.visit_return(node) - @set_config(accept_no_return_doc="no") def test_ignores_non_property_return_type_google(self) -> None: """Example of a class function trying to use `type` as return @@ -2079,27 +1575,6 @@ def foo(self) -> int: #@ ): self.checker.visit_return(node) - def test_ignores_return_in_abstract_method_sphinx(self) -> None: - """Example of an abstract method documenting the return type that an - implementation should return. - """ - node = astroid.extract_node( - """ - import abc - class Foo(object): - @abc.abstractmethod - def foo(self): #@ - '''docstring ... - - :returns: Ten - :rtype: int - ''' - return 10 - """ - ) - with self.assertNoMessages(): - self.checker.visit_functiondef(node) - def test_ignores_return_in_abstract_method_google(self) -> None: """Example of an abstract method documenting the return type that an implementation should return. @@ -2144,23 +1619,6 @@ def foo(self): #@ with self.assertNoMessages(): self.checker.visit_functiondef(node) - def test_ignores_raise_notimplementederror_sphinx(self) -> None: - """Example of an abstract""" - node = astroid.extract_node( - """ - class Foo(object): - def foo(self, arg): #@ - '''docstring ... - - :param arg: An argument. - :type arg: int - ''' - raise NotImplementedError() - """ - ) - with self.assertNoMessages(): - self.checker.visit_functiondef(node) - def test_ignores_return_in_abstract_method_google_2(self) -> None: """Example of a method documenting the return type that an implementation should return. @@ -2201,25 +1659,6 @@ def foo(self, arg): #@ with self.assertNoMessages(): self.checker.visit_functiondef(node) - def test_ignores_ignored_argument_names_sphinx(self) -> None: - """Example of a method documenting the return type that an - implementation should return. - """ - node = astroid.extract_node( - """ - class Foo(object): - def foo(self, arg, _): #@ - '''docstring ... - - :param arg: An argument. - :type arg: int - ''' - pass - """ - ) - with self.assertNoMessages(): - self.checker.visit_functiondef(node) - def test_ignores_ignored_argument_names_google(self) -> None: """Example of a method documenting the return type that an implementation should return. @@ -2260,33 +1699,6 @@ def foo(self, arg, _): #@ with self.assertNoMessages(): self.checker.visit_functiondef(node) - def test_useless_docs_ignored_argument_names_sphinx(self) -> None: - """Example of a method documenting the return type that an - implementation should return. - """ - node = astroid.extract_node( - """ - class Foo(object): - def foo(self, arg, _, _ignored): #@ - '''docstring ... - - :param arg: An argument. - :type arg: int - - :param _: Another argument. - :type _: float - - :param _ignored: Ignored argument. - ''' - pass - """ - ) - with self.assertAddsMessages( - MessageTest(msg_id="useless-type-doc", node=node, args=("_",)), - MessageTest(msg_id="useless-param-doc", node=node, args=("_, _ignored",)), - ): - self.checker.visit_functiondef(node) - def test_useless_docs_ignored_argument_names_google(self) -> None: """Example of a method documenting the return type that an implementation should return. diff --git a/tests/functional/ext/docparams/parameter/missing_param_doc_required_Sphinx.py b/tests/functional/ext/docparams/parameter/missing_param_doc_required_Sphinx.py new file mode 100644 index 0000000000..e7b5310d95 --- /dev/null +++ b/tests/functional/ext/docparams/parameter/missing_param_doc_required_Sphinx.py @@ -0,0 +1,418 @@ +"""Tests for missing-param-doc and missing-type-doc for Sphinx style docstrings +with accept-no-param-doc = no""" +# pylint: disable=function-redefined, invalid-name, undefined-variable, missing-class-docstring +# pylint: disable=unused-argument, too-few-public-methods, unnecessary-pass, line-too-long +# pylint: disable=missing-function-docstring, disallowed-name, no-self-use + + +def test_missing_func_params_in_sphinx_docstring( # [missing-param-doc, missing-type-doc] + x, y, z +): + """Example of a function with missing Sphinx parameter documentation in + the docstring + + :param x: bla + + :param int z: bar + """ + pass + + +class Foo: + def test_missing_method_params_in_sphinx_docstring( # [missing-param-doc, missing-type-doc] + self, x, y + ): + """Example of a class method with missing parameter documentation in + the Sphinx style docstring + + missing parameter documentation + + :param x: bla + """ + pass + + +def test_existing_func_params_in_sphinx_docstring(xarg, yarg, zarg, warg): + """Example of a function with correctly documented parameters and + return values (Sphinx style) + + :param xarg: bla xarg + :type xarg: int + + :parameter yarg: bla yarg + :type yarg: my.qualified.type + + :arg int zarg: bla zarg + + :keyword my.qualified.type warg: bla warg + + :return: sum + :rtype: float + """ + return xarg + yarg + + +def test_wrong_name_of_func_params_in_sphinx_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 Sphinx style documentation + + :param xarg1: bla xarg + :type xarg: int + + :param yarg: bla yarg + :type yarg1: float + + :param str zarg1: bla zarg + """ + return xarg + yarg + + +def test_wrong_name_of_func_params_in_sphinx_docstring_two( # [differing-param-doc, differing-type-doc] + xarg, yarg, zarg +): + """Example of functions with inconsistent parameter names in the + signature and in the Sphinx style documentation + + :param yarg1: bla yarg + :type yarg1: float + + For the other parameters, see bla. + """ + return xarg + yarg + + +def test_see_sentence_for_func_params_in_sphinx_docstring(xarg, yarg) -> None: + """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 (Sphinx style) + + :param yarg: bla yarg + :type yarg: float + + For the other parameters, see :func:`bla` + """ + return xarg + yarg + + +class ClassFoo: # [missing-param-doc, missing-type-doc] + """test_constr_params_in_class_sphinx + Example of a class with missing constructor parameter documentation + (Sphinx style) + + Everything is completely analogous to functions. + + :param y: bla + + missing constructor parameter documentation + """ + + def __init__(self, x, y): + pass + + +class ClassFoo: + def __init__(self, x, y): # [missing-param-doc, missing-type-doc] + """test_constr_params_in_init_sphinx + Example of a class with missing constructor parameter documentation + (Sphinx style) + + Everything is completely analogous to functions. + + :param y: bla + + missing constructor parameter documentation + """ + + pass + + +class ClassFoo: # [multiple-constructor-doc, missing-param-doc, missing-type-doc] + """test_constr_params_in_class_and_init_sphinx + Example of a class with missing constructor parameter documentation + in both the init docstring and the class docstring + (Sphinx style) + + Everything is completely analogous to functions. + + :param y: None + + missing constructor parameter documentation + """ + + def __init__(self, x, y): # [missing-param-doc, missing-type-doc] + """docstring foo + + :param y: bla + + missing constructor parameter documentation + """ + pass + + +def test_warns_missing_args_sphinx( # [missing-param-doc, inconsistent-return-statements] + named_arg, *args +): + """The docstring + + :param named_arg: Returned + :type named_arg: object + :returns: Maybe named_arg + :rtype: object or None + """ + if args: + return named_arg + + +def test_warns_missing_kwargs_sphinx( # [missing-param-doc, inconsistent-return-statements] + named_arg, **kwargs +): + """The docstring + + :param named_arg: Returned + :type named_arg: object + :returns: Maybe named_arg + :rtype: object or None + """ + if kwargs: + return named_arg + + +def test_finds_args_without_type_sphinx( # [inconsistent-return-statements] + named_arg, *args +): + """The docstring + + :param named_arg: Returned + :type named_arg: object + :param *args: Optional arguments + :returns: Maybe named_arg + :rtype: object or None + """ + if args: + return named_arg + + +def test_finds_kwargs_without_type_sphinx( # [inconsistent-return-statements] + named_arg, **kwargs +): + """The docstring + + :param named_arg: Returned + :type named_arg: object + :param **kwargs: Keyword arguments + :returns: Maybe named_arg + :rtype: object or None + """ + if kwargs: + return named_arg + + +class Foo: + """test_finds_missing_raises_from_setter_sphinx + Example of a setter having missing raises documentation in + the Sphinx style docstring of the property + """ + + @property + def foo(self): # [missing-raises-doc] + """docstring ... + + :type: int + """ + return 10 + + @foo.setter + def foo(self, value): + raise AttributeError() + + +class Foo: + """test_finds_missing_raises_in_setter_sphinx + Example of a setter having missing raises documentation in + its own Sphinx style docstring + """ + + @property + def foo(self): + """docstring ... + + :type: int + :raises RuntimeError: Always + """ + raise RuntimeError() + return 10 # [unreachable] + + @foo.setter + def foo(self, value): # [missing-raises-doc, missing-param-doc, missing-type-doc] + """setter docstring ... + + :type: None + """ + raise AttributeError() + + +class Foo: + """test_finds_property_return_type_sphinx + Example of a property having return documentation in + a Sphinx style docstring + """ + + @property + def foo(self): + """docstring ... + + :type: int + """ + return 10 + + +class Foo: + """test_finds_annotation_property_return_type_sphinx + Example of a property having missing return documentation in + a Sphinx style docstring + """ + + @property + def foo(self) -> int: + """docstring ... + + :raises RuntimeError: Always + """ + raise RuntimeError() + return 10 # [unreachable] + + +class Foo: + def test_useless_docs_ignored_argument_names_sphinx( # [useless-type-doc, useless-param-doc] + self, arg, _, _ignored + ): + """Example of a method documenting the return type that an + implementation should return. + + :param arg: An argument. + :type arg: int + + :param _: Another argument. + :type _: float + + :param _ignored: Ignored argument. + """ + pass + + +def test_finds_multiple_types_sphinx_one(named_arg): + """The Sphinx docstring + + :param named_arg: Returned + :type named_arg: dict(str, str) + + :returns: named_arg + :rtype: dict(str, str) + """ + return named_arg + + +def test_finds_multiple_types_sphinx_two(named_arg): + """The Sphinx docstring + + :param named_arg: Returned + :type named_arg: dict[str, str] + + :returns: named_arg + :rtype: dict[str, str] + """ + return named_arg + + +def test_finds_multiple_types_sphinx_three(named_arg): + """The Sphinx docstring + + :param named_arg: Returned + :type named_arg: int or str + + :returns: named_arg + :rtype: int or str + """ + return named_arg + + +def test_finds_multiple_types_sphinx_four(named_arg): + """The Sphinx docstring + + :param named_arg: Returned + :type named_arg: tuple(int or str) + + :returns: named_arg + :rtype: tuple(int or str) + """ + return named_arg + + +def test_finds_multiple_types_sphinx_five(named_arg): + """The Sphinx docstring + + :param named_arg: Returned + :type named_arg: tuple(int) or list(int) + + :returns: named_arg + :rtype: tuple(int) or list(int) + """ + return named_arg + + +def test_finds_multiple_types_sphinx_six(named_arg): + """The Sphinx docstring + + :param named_arg: Returned + :type named_arg: tuple(int or str) or list(int or str) + + :returns: named_arg + :rtype: tuple(int or str) or list(int or str) + """ + return named_arg + + +def test_finds_compact_container_types_sphinx_one(named_arg): + """The Sphinx docstring + + :param dict(str,str) named_arg: Returned + + :returns: named_arg + :rtype: dict(str,str) + """ + return named_arg + + +def test_finds_compact_container_types_sphinx_two(named_arg): + """The Sphinx docstring + + :param dict[str,str] named_arg: Returned + + :returns: named_arg + :rtype: dict[str,str] + """ + return named_arg + + +def test_finds_compact_container_types_sphinx_three(named_arg): + """The Sphinx docstring + + :param tuple(int) named_arg: Returned + + :returns: named_arg + :rtype: tuple(int) + """ + return named_arg + + +def test_finds_compact_container_types_sphinx_four(named_arg): + """The Sphinx docstring + + :param list[tokenize.TokenInfo] named_arg: Returned + + :returns: named_arg + :rtype: list[tokenize.TokenInfo] + """ + return named_arg diff --git a/tests/functional/ext/docparams/parameter/missing_param_doc_required_Sphinx.rc b/tests/functional/ext/docparams/parameter/missing_param_doc_required_Sphinx.rc new file mode 100644 index 0000000000..4fc587b6c8 --- /dev/null +++ b/tests/functional/ext/docparams/parameter/missing_param_doc_required_Sphinx.rc @@ -0,0 +1,7 @@ +[MASTER] +load-plugins = pylint.extensions.docparams + +[BASIC] +accept-no-param-doc=no +no-docstring-rgx=^$ +docstring-min-length: -1 diff --git a/tests/functional/ext/docparams/parameter/missing_param_doc_required_Sphinx.txt b/tests/functional/ext/docparams/parameter/missing_param_doc_required_Sphinx.txt new file mode 100644 index 0000000000..9eb927663a --- /dev/null +++ b/tests/functional/ext/docparams/parameter/missing_param_doc_required_Sphinx.txt @@ -0,0 +1,33 @@ +missing-param-doc:8:0:18:8:test_missing_func_params_in_sphinx_docstring:"""y"" missing in parameter documentation":UNDEFINED +missing-type-doc:8:0:18:8:test_missing_func_params_in_sphinx_docstring:"""x, y"" missing in parameter type documentation":UNDEFINED +missing-param-doc:22:4:32:12:Foo.test_missing_method_params_in_sphinx_docstring:"""y"" missing in parameter documentation":UNDEFINED +missing-type-doc:22:4:32:12:Foo.test_missing_method_params_in_sphinx_docstring:"""x, y"" missing in parameter type documentation":UNDEFINED +differing-param-doc:55:0:69:22:test_wrong_name_of_func_params_in_sphinx_docstring:"""xarg1, zarg1"" differing in parameter documentation":UNDEFINED +differing-type-doc:55:0:69:22:test_wrong_name_of_func_params_in_sphinx_docstring:"""yarg1, zarg1"" differing in parameter type documentation":UNDEFINED +missing-param-doc:55:0:69:22:test_wrong_name_of_func_params_in_sphinx_docstring:"""xarg, zarg"" missing in parameter documentation":UNDEFINED +missing-type-doc:55:0:69:22:test_wrong_name_of_func_params_in_sphinx_docstring:"""yarg, zarg"" missing in parameter type documentation":UNDEFINED +differing-param-doc:72:0:83:22:test_wrong_name_of_func_params_in_sphinx_docstring_two:"""yarg1"" differing in parameter documentation":UNDEFINED +differing-type-doc:72:0:83:22:test_wrong_name_of_func_params_in_sphinx_docstring_two:"""yarg1"" differing in parameter type documentation":UNDEFINED +missing-param-doc:99:0:112:12:ClassFoo:"""x"" missing in parameter documentation":UNDEFINED +missing-type-doc:99:0:112:12:ClassFoo:"""x, y"" missing in parameter type documentation":UNDEFINED +missing-param-doc:116:4:128:12:ClassFoo.__init__:"""x"" missing in parameter documentation":UNDEFINED +missing-type-doc:116:4:128:12:ClassFoo.__init__:"""x, y"" missing in parameter type documentation":UNDEFINED +missing-param-doc:131:0:151:12:ClassFoo:"""x"" missing in parameter documentation":UNDEFINED +missing-type-doc:131:0:151:12:ClassFoo:"""x, y"" missing in parameter type documentation":UNDEFINED +multiple-constructor-doc:131:0:151:12:ClassFoo:"""ClassFoo"" has constructor parameters documented in class and __init__":UNDEFINED +missing-param-doc:144:4:151:12:ClassFoo.__init__:"""x"" missing in parameter documentation":UNDEFINED +missing-type-doc:144:4:151:12:ClassFoo.__init__:"""x, y"" missing in parameter type documentation":UNDEFINED +inconsistent-return-statements:154:0:165:24:test_warns_missing_args_sphinx:Either all return statements in a function should return an expression, or none of them should.:UNDEFINED +missing-param-doc:154:0:165:24:test_warns_missing_args_sphinx:"""*args"" missing in parameter documentation":UNDEFINED +inconsistent-return-statements:168:0:179:24:test_warns_missing_kwargs_sphinx:Either all return statements in a function should return an expression, or none of them should.:UNDEFINED +missing-param-doc:168:0:179:24:test_warns_missing_kwargs_sphinx:"""**kwargs"" missing in parameter documentation":UNDEFINED +inconsistent-return-statements:182:0:194:24:test_finds_args_without_type_sphinx:Either all return statements in a function should return an expression, or none of them should.:UNDEFINED +inconsistent-return-statements:197:0:209:24:test_finds_kwargs_without_type_sphinx:Either all return statements in a function should return an expression, or none of them should.:UNDEFINED +missing-raises-doc:219:4:224:17:Foo.foo:"""AttributeError"" not documented as being raised":UNDEFINED +unreachable:245:8:245:17:Foo.foo:Unreachable code:UNDEFINED +missing-param-doc:248:4:253:30:Foo.foo:"""value"" missing in parameter documentation":UNDEFINED +missing-raises-doc:248:4:253:30:Foo.foo:"""AttributeError"" not documented as being raised":UNDEFINED +missing-type-doc:248:4:253:30:Foo.foo:"""value"" missing in parameter type documentation":UNDEFINED +unreachable:284:8:284:17:Foo.foo:Unreachable code:UNDEFINED +useless-param-doc:288:4:302:12:Foo.test_useless_docs_ignored_argument_names_sphinx:"""_, _ignored"" useless ignored parameter documentation":UNDEFINED +useless-type-doc:288:4:302:12:Foo.test_useless_docs_ignored_argument_names_sphinx:"""_"" useless ignored parameter type documentation":UNDEFINED diff --git a/tests/functional/ext/docparams/raise/missing_raises_doc_Sphinx.py b/tests/functional/ext/docparams/raise/missing_raises_doc_Sphinx.py index c3be7c6d65..91a603b711 100644 --- a/tests/functional/ext/docparams/raise/missing_raises_doc_Sphinx.py +++ b/tests/functional/ext/docparams/raise/missing_raises_doc_Sphinx.py @@ -1,6 +1,7 @@ """Tests for missing-raises-doc and missing-raises-type-doc for Sphinx style docstrings""" # pylint: disable=function-redefined, invalid-name, undefined-variable, missing-function-docstring # pylint: disable=unused-argument, try-except-raise, import-outside-toplevel +# pylint: disable=missing-class-docstring, too-few-public-methods def test_find_missing_sphinx_raises(self): # [missing-raises-doc] @@ -149,3 +150,13 @@ def test_find_invalid_missing_sphinx_attr_raises(self): from re import error raise error("hi") + + +class Foo: + def test_ignores_raise_notimplementederror_sphinx(self, arg): + """docstring ... + + :param arg: An argument. + :type arg: int + """ + raise NotImplementedError() diff --git a/tests/functional/ext/docparams/raise/missing_raises_doc_Sphinx.txt b/tests/functional/ext/docparams/raise/missing_raises_doc_Sphinx.txt index e5a091e469..77dbea7080 100644 --- a/tests/functional/ext/docparams/raise/missing_raises_doc_Sphinx.txt +++ b/tests/functional/ext/docparams/raise/missing_raises_doc_Sphinx.txt @@ -1,13 +1,13 @@ -missing-raises-doc:6:0:12:25:test_find_missing_sphinx_raises:"""RuntimeError"" not documented as being raised":UNDEFINED -unreachable:12:4:12:25:test_find_missing_sphinx_raises:Unreachable code:UNDEFINED -unreachable:35:4:35:25:test_find_all_sphinx_raises:Unreachable code:UNDEFINED -unreachable:36:4:36:30:test_find_all_sphinx_raises:Unreachable code:UNDEFINED -unreachable:37:4:37:27:test_find_all_sphinx_raises:Unreachable code:UNDEFINED -unreachable:47:4:47:25:test_find_multiple_sphinx_raises:Unreachable code:UNDEFINED -missing-raises-doc:50:0:60:25:test_finds_rethrown_sphinx_raises:"""RuntimeError"" not documented as being raised":UNDEFINED -missing-raises-doc:63:0:73:25:test_finds_rethrown_sphinx_multiple_raises:"""RuntimeError, ValueError"" not documented as being raised":UNDEFINED -missing-raises-doc:89:0:96:25:test_find_missing_sphinx_raises_infer_from_instance:"""RuntimeError"" not documented as being raised":UNDEFINED -unreachable:96:4:96:25:test_find_missing_sphinx_raises_infer_from_instance:Unreachable code:UNDEFINED -missing-raises-doc:99:0:109:25:test_find_missing_sphinx_raises_infer_from_function:"""RuntimeError"" not documented as being raised":UNDEFINED -unreachable:109:4:109:25:test_find_missing_sphinx_raises_infer_from_function:Unreachable code:UNDEFINED -missing-raises-doc:132:0:139:21:test_find_valid_missing_sphinx_attr_raises:"""error"" not documented as being raised":UNDEFINED +missing-raises-doc:7:0:13:25:test_find_missing_sphinx_raises:"""RuntimeError"" not documented as being raised":UNDEFINED +unreachable:13:4:13:25:test_find_missing_sphinx_raises:Unreachable code:UNDEFINED +unreachable:36:4:36:25:test_find_all_sphinx_raises:Unreachable code:UNDEFINED +unreachable:37:4:37:30:test_find_all_sphinx_raises:Unreachable code:UNDEFINED +unreachable:38:4:38:27:test_find_all_sphinx_raises:Unreachable code:UNDEFINED +unreachable:48:4:48:25:test_find_multiple_sphinx_raises:Unreachable code:UNDEFINED +missing-raises-doc:51:0:61:25:test_finds_rethrown_sphinx_raises:"""RuntimeError"" not documented as being raised":UNDEFINED +missing-raises-doc:64:0:74:25:test_finds_rethrown_sphinx_multiple_raises:"""RuntimeError, ValueError"" not documented as being raised":UNDEFINED +missing-raises-doc:90:0:97:25:test_find_missing_sphinx_raises_infer_from_instance:"""RuntimeError"" not documented as being raised":UNDEFINED +unreachable:97:4:97:25:test_find_missing_sphinx_raises_infer_from_instance:Unreachable code:UNDEFINED +missing-raises-doc:100:0:110:25:test_find_missing_sphinx_raises_infer_from_function:"""RuntimeError"" not documented as being raised":UNDEFINED +unreachable:110:4:110:25:test_find_missing_sphinx_raises_infer_from_function:Unreachable code:UNDEFINED +missing-raises-doc:133:0:140:21:test_find_valid_missing_sphinx_attr_raises:"""error"" not documented as being raised":UNDEFINED diff --git a/tests/functional/ext/docparams/return/missing_return_doc_Sphinx.py b/tests/functional/ext/docparams/return/missing_return_doc_Sphinx.py index 55bf569198..41b0ce1ae5 100644 --- a/tests/functional/ext/docparams/return/missing_return_doc_Sphinx.py +++ b/tests/functional/ext/docparams/return/missing_return_doc_Sphinx.py @@ -1,6 +1,8 @@ """Tests for missing-return-doc and missing-return-type-doc for Sphinx style docstrings""" # pylint: disable=function-redefined, invalid-name, undefined-variable, missing-function-docstring -# pylint: disable=unused-argument +# pylint: disable=unused-argument, disallowed-name, too-few-public-methods, missing-class-docstring +# pylint: disable=unnecessary-pass +import abc def my_func(self): @@ -77,3 +79,31 @@ def my_func_with_yield(self): """ for value in range(3): yield value + + +class Foo: + """test_ignores_return_in_abstract_method_sphinx + Example of an abstract method documenting the return type that an + implementation should return. + """ + + @abc.abstractmethod + def foo(self): + """docstring ... + + :returns: Ten + :rtype: int + """ + return 10 + + +class Foo: + def test_ignores_ignored_argument_names_sphinx(self, arg, _): + """Example of a method documenting the return type that an + implementation should return. + + + :param arg: An argument. + :type arg: int + """ + pass diff --git a/tests/functional/ext/docparams/return/missing_return_doc_Sphinx.txt b/tests/functional/ext/docparams/return/missing_return_doc_Sphinx.txt index 5d7ace227b..604b5d0955 100644 --- a/tests/functional/ext/docparams/return/missing_return_doc_Sphinx.txt +++ b/tests/functional/ext/docparams/return/missing_return_doc_Sphinx.txt @@ -1,2 +1,2 @@ -redundant-returns-doc:42:0:47:15:my_func:Redundant returns documentation:UNDEFINED -redundant-returns-doc:50:0:55:15:my_func:Redundant returns documentation:UNDEFINED +redundant-returns-doc:44:0:49:15:my_func:Redundant returns documentation:UNDEFINED +redundant-returns-doc:52:0:57:15:my_func:Redundant returns documentation:UNDEFINED diff --git a/tests/functional/ext/docparams/return/missing_return_doc_required_Sphinx.py b/tests/functional/ext/docparams/return/missing_return_doc_required_Sphinx.py index 61be7696e7..50ae7033ba 100644 --- a/tests/functional/ext/docparams/return/missing_return_doc_required_Sphinx.py +++ b/tests/functional/ext/docparams/return/missing_return_doc_required_Sphinx.py @@ -1,7 +1,8 @@ """Tests for missing-return-doc and missing-return-type-doc for Sphinx style docstrings with accept-no-returns-doc = no""" # pylint: disable=function-redefined, invalid-name, undefined-variable, missing-function-docstring -# pylint: disable=unused-argument +# pylint: disable=unused-argument, disallowed-name, too-few-public-methods +# pylint: disable=no-self-use, line-too-long def my_func(self): # [missing-return-type-doc] @@ -28,7 +29,9 @@ def my_func(self): # [missing-return-doc] return False -def warn_missing_sphinx_returns(self, doc_type): # [missing-return-type-doc, missing-return-doc] +def warn_missing_sphinx_returns( # [missing-return-type-doc, missing-return-doc] + self, doc_type +): """This is a docstring. :param doc_type: Sphinx @@ -43,3 +46,34 @@ def my_func(self): # [missing-return-doc] :rtype: list(:class:`mymodule.Class`) """ return [mymodule.Class()] + + +class Foo: + """test_finds_missing_property_return_type_sphinx + Example of a property having missing return documentation in + a Sphinx style docstring + """ + + @property + def foo(self): # [missing-return-type-doc] + """docstring ... + + :raises RuntimeError: Always + """ + raise RuntimeError() + return 10 # [unreachable] + + +class Foo: + """Example of a class function trying to use `type` as return + documentation in a Sphinx style docstring + """ + + def test_ignores_non_property_return_type_sphinx( # [missing-return-doc, missing-return-type-doc] + self, + ): + """docstring ... + + :type: int + """ + return 10 diff --git a/tests/functional/ext/docparams/return/missing_return_doc_required_Sphinx.txt b/tests/functional/ext/docparams/return/missing_return_doc_required_Sphinx.txt index 6fe45c67f5..0d35b88edd 100644 --- a/tests/functional/ext/docparams/return/missing_return_doc_required_Sphinx.txt +++ b/tests/functional/ext/docparams/return/missing_return_doc_required_Sphinx.txt @@ -1,5 +1,9 @@ -missing-return-type-doc:7:0:12:16:my_func:Missing return type documentation:UNDEFINED -missing-return-doc:23:0:28:16:my_func:Missing return documentation:UNDEFINED -missing-return-doc:31:0:37:16:warn_missing_sphinx_returns:Missing return documentation:UNDEFINED -missing-return-type-doc:31:0:37:16:warn_missing_sphinx_returns:Missing return type documentation:UNDEFINED -missing-return-doc:40:0:45:29:my_func:Missing return documentation:UNDEFINED +missing-return-type-doc:8:0:13:16:my_func:Missing return type documentation:UNDEFINED +missing-return-doc:24:0:29:16:my_func:Missing return documentation:UNDEFINED +missing-return-doc:32:0:40:16:warn_missing_sphinx_returns:Missing return documentation:UNDEFINED +missing-return-type-doc:32:0:40:16:warn_missing_sphinx_returns:Missing return type documentation:UNDEFINED +missing-return-doc:43:0:48:29:my_func:Missing return documentation:UNDEFINED +missing-return-type-doc:58:4:64:17:Foo.foo:Missing return type documentation:UNDEFINED +unreachable:64:8:64:17:Foo.foo:Unreachable code:UNDEFINED +missing-return-doc:72:4:79:17:Foo.test_ignores_non_property_return_type_sphinx:Missing return documentation:UNDEFINED +missing-return-type-doc:72:4:79:17:Foo.test_ignores_non_property_return_type_sphinx:Missing return type documentation:UNDEFINED