merge

1 files changed, 191 insertions, 0 deletions

diff --git a/test/extensions/test_check_docs.py b/test/extensions/test_check_docs.py
new file mode 100644
index 0000000..59f5d7e
--- /dev/null
+++ b/test/extensions/test_check_docs.py
@@ -0,0 +1,191 @@
+"""Unit tests for the pylint checkers in :mod:`pylint.extensions.check_docs`,
+in particular the Sphinx parameter documentation checker `SphinxDocChecker`
+"""
+from __future__ import division, print_function, absolute_import
+
+import unittest
+
+from astroid import test_utils
+from pylint.testutils import CheckerTestCase, Message
+
+from pylint.extensions.check_docs import SphinxDocChecker
+
+
+class SpinxDocCheckerTest(CheckerTestCase):
+    """Tests for pylint_plugin.SphinxDocChecker"""
+    CHECKER_CLASS = SphinxDocChecker
+
+    def test_missing_func_params_in_docstring(self):
+        """Example of a function with missing parameter documentation in the
+        docstring
+        """
+        node = test_utils.extract_node("""
+        def function_foo(x, y):
+            '''docstring ...
+
+            missing parameter documentation'''
+            pass
+        """)
+        with self.assertAddsMessages(
+            Message(
+                msg_id='missing-sphinx-param',
+                node=node,
+                args=('x, y',)),
+            Message(
+                msg_id='missing-sphinx-type',
+                node=node,
+                args=('x, y',))
+        ):
+            self.checker.visit_function(node)
+
+    def test_missing_method_params_in_docstring(self):
+        """Example of a class method with missing parameter documentation in
+        the docstring
+        """
+        node = test_utils.extract_node("""
+        class Foo(object):
+            def method_foo(self, x, y):
+                '''docstring ...
+
+                missing parameter documentation'''
+                pass
+        """)
+        method_node = node.body[0]
+        with self.assertAddsMessages(
+            Message(
+                msg_id='missing-sphinx-param',
+                node=method_node,
+                args=('x, y',)),
+            Message(
+                msg_id='missing-sphinx-type',
+                node=method_node,
+                args=('x, y',))
+        ):
+            self.checker.visit_class(node)
+
+    def test_existing_func_params_in_docstring(self):
+        """Example of a function with correctly documented parameters and
+        return values
+        """
+        node = test_utils.extract_node("""
+        def function_foo(xarg, yarg, zarg):
+            '''function foo ...
+
+            :param xarg: bla xarg
+            :type xarg: int
+
+            :param yarg: bla yarg
+            :type yarg: float
+
+            :param int zarg: bla zarg
+
+            :return: sum
+            :rtype: float
+            '''
+            return xarg + yarg
+        """)
+        with self.assertNoMessages():
+            self.checker.visit_function(node)
+
+    def test_wrong_name_of_func_params_in_docstring(self):
+        """Example of functions with inconsistent parameter names in the
+        signature and in the documentation
+        """
+        node = test_utils.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(
+            Message(
+                msg_id='missing-sphinx-param',
+                node=node,
+                args=('xarg, xarg1, zarg, zarg1',)),
+            Message(
+                msg_id='missing-sphinx-type',
+                node=node,
+                args=('yarg, yarg1, zarg',)),
+        ):
+            self.checker.visit_function(node)
+
+        node = test_utils.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(
+            Message(
+                msg_id='missing-sphinx-param',
+                node=node,
+                args=('yarg1',)),
+            Message(
+                msg_id='missing-sphinx-type',
+                node=node,
+                args=('yarg1',))
+        ):
+            self.checker.visit_function(node)
+
+    def test_see_sentence_for_func_params_in_docstring(self):
+        """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
+        """
+        node = test_utils.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_function(node)
+
+    def test_constr_params_in_class(self):
+        """Example of a class with missing constructor parameter documentation
+
+        Everything is completely analogous to functions.
+        """
+        node = test_utils.extract_node("""
+        class ClassFoo(object):
+            '''docstring foo
+
+            missing constructor parameter documentation'''
+
+            def __init__(self, x, y):
+                pass
+
+        """)
+        with self.assertAddsMessages(
+            Message(
+                msg_id='missing-sphinx-param',
+                node=node,
+                args=('x, y',)),
+            Message(
+                msg_id='missing-sphinx-type',
+                node=node,
+                args=('x, y',))
+        ):
+            self.checker.visit_class(node)
+
+
+if __name__ == '__main__':
+    unittest.main()