Move Sphinx docstrings out of TestParamDocChecker (#5450)

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

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

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()

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

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

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

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

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