Take annotations in account for missing-type-doc and missing-return-doc

Close #2083

6 files changed, 200 insertions, 1 deletions

diff --git a/CONTRIBUTORS.txt b/CONTRIBUTORS.txt
index 7e304dfcd..f0bf4fd78 100644
--- a/CONTRIBUTORS.txt
+++ b/CONTRIBUTORS.txt
@@ -183,7 +183,8 @@ Order doesn't matter (not that much, at least ;)
 
 * Sushobhit (sushobhit27): contributor
   Added new check 'comparison-with-itself'.
-
+  Added support of annotations in missing-type-doc and missing-return-type-doc.
+  
 * Mariatta Wijaya: contributor
   Added new check `logging-fstring-interpolation`
   Documentation typo fixes
diff --git a/ChangeLog b/ChangeLog
index facaf8b44..9f82b7d78 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -3,6 +3,9 @@ Pylint's ChangeLog
 ------------------
 What's New in Pylint 2.0?
 =========================
+    * Don't warn for ``missing-type-doc`` and/or ``missing-return-type-doc``, if type
+      annotations exist on the function signature for a parameter and/or return type.
+      Close #2083
 
 Release date: |TBA|
 
diff --git a/doc/whatsnew/2.0.rst b/doc/whatsnew/2.0.rst
index 4e8db27b0..1f34c1d4b 100644
--- a/doc/whatsnew/2.0.rst
+++ b/doc/whatsnew/2.0.rst
@@ -141,6 +141,8 @@ New checkers
 
 Other Changes
 =============
+* Don't warn for ``missing-type-doc`` and/or ``missing-return-type-doc``, if type annotations
+  exist on the function signature for a parameter and/or return type.
 
 * Fix a false positive ``inconsistent-return-statements`` message when if
   statement is inside try/except.
diff --git a/pylint/extensions/docparams.py b/pylint/extensions/docparams.py
index 9533d191d..a73677486 100644
--- a/pylint/extensions/docparams.py
+++ b/pylint/extensions/docparams.py
@@ -237,6 +237,9 @@ class DocstringParameterChecker(BaseChecker):
                 node=func_node
             )
 
+        if func_node.returns:
+            return
+
         if not (doc.has_rtype() or
                 (doc.has_property_type() and is_property)):
             self.add_message(
@@ -388,6 +391,11 @@ class DocstringParameterChecker(BaseChecker):
 
         _compare_missing_args(params_with_doc, 'missing-param-doc',
                               self.not_needed_param_in_docstring)
+
+        for index, arg_name in enumerate(arguments_node.args):
+            if arguments_node.annotations[index]:
+                params_with_type.add(arg_name.name)
+
         _compare_missing_args(params_with_type, 'missing-type-doc',
                               not_needed_type_in_docstring)
 
diff --git a/pylint/test/extensions/test_check_docs.py b/pylint/test/extensions/test_check_docs.py
index f8700e823..de18d55c2 100644
--- a/pylint/test/extensions/test_check_docs.py
+++ b/pylint/test/extensions/test_check_docs.py
@@ -87,6 +87,103 @@ class TestParamDocChecker(CheckerTestCase):
         ):
             self.checker.visit_functiondef(node)
 
+    def test_missing_func_params_with_annotations_in_google_docstring(self):
+        """Example of a function with missing Google style parameter
+        documentation in the docstring.
+        """
+        node = astroid.extract_node("""
+        def function_foo(x: int, y: bool, z):
+            '''docstring ...
+
+            Args:
+                x: bla
+                y: blah blah
+                z (int): bar
+
+            some other stuff
+            '''
+            pass
+        """)
+        with self.assertNoMessages():
+            self.checker.visit_functiondef(node)
+
+    def test_default_arg_with_annotations_in_google_docstring(self):
+        """Example of a function with missing Google style parameter
+        documentation in the docstring.
+        """
+        node = astroid.extract_node("""
+        def function_foo(x: int, y: bool, z: int = 786):
+            '''docstring ...
+
+            Args:
+                x: bla
+                y: blah blah
+                z: bar
+
+            some other stuff
+            '''
+            pass
+        """)
+        with self.assertNoMessages():
+            self.checker.visit_functiondef(node)
+
+    def test_missing_func_params_with_partial_annotations_in_google_docstring(self):
+        """Example of a function with missing Google style parameter
+        documentation in the docstring.
+        """
+        node = astroid.extract_node("""
+        def function_foo(x, y: bool, z):
+            '''docstring ...
+
+            Args:
+                x: bla
+                y: blah blah
+                z (int): bar
+
+            some other stuff
+            '''
+            pass
+        """)
+        with self.assertAddsMessages(
+                Message(
+                    msg_id='missing-type-doc',
+                    node=node,
+                    args=('x',))
+        ):
+            self.checker.visit_functiondef(node)
+
+    def test_non_builtin_annotations_in_google_docstring(self):
+        """Example of a function with missing Google style parameter
+        documentation in the docstring.
+        """
+        node = astroid.extract_node("""
+        def area(bottomleft: Point, topright: Point) -> float:
+            '''Calculate area of fake rectangle.
+                Args:
+                    bottomleft: bottom left point of rectangle
+                    topright: top right point of rectangle
+            '''
+            pass
+        """)
+        with self.assertNoMessages():
+            self.checker.visit_functiondef(node)
+
+    def test_non_builtin_annotations_for_returntype_in_google_docstring(self):
+        """Example of a function with missing Google style parameter
+        documentation in the docstring.
+        """
+        node = astroid.extract_node("""
+        def get_midpoint(bottomleft: Point, topright: Point) -> Point:
+            '''Calculate midpoint of fake rectangle.
+                Args:
+                    bottomleft: bottom left point of rectangle
+                    topright: top right point of rectangle
+            '''
+            pass
+        """)
+        with self.assertNoMessages():
+            self.checker.visit_functiondef(node)
+
     def test_func_params_and_keyword_params_in_google_docstring(self):
         """Example of a function with Google style parameter splitted
         in Args and Keyword Args in the docstring
@@ -1775,6 +1872,24 @@ class TestParamDocChecker(CheckerTestCase):
         with self.assertNoMessages():
             self.checker.visit_functiondef(node)
 
+    def test_finds_annotation_property_return_type_sphinx(self):
+        """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) -> int: #@
+                '''docstring ...
+
+                :raises RuntimeError: Always
+                '''
+                raise RuntimeError()
+                return 10 #@
+        """)
+        with self.assertNoMessages():
+            self.checker.visit_return(node)
+
     def test_finds_missing_property_return_type_sphinx(self):
         """Example of a property having missing return documentation in
         a Sphinx style docstring
@@ -1797,6 +1912,25 @@ class TestParamDocChecker(CheckerTestCase):
         ):
             self.checker.visit_return(node)
 
+    def test_finds_annotation_property_return_type_google(self):
+        """Example of a property having return documentation in
+        a Google style docstring
+        """
+        property_node, 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)
+
     def test_finds_missing_property_return_type_google(self):
         """Example of a property having return documentation in
         a Google style docstring
@@ -1920,6 +2054,30 @@ class TestParamDocChecker(CheckerTestCase):
         ):
             self.checker.visit_return(node)
 
+    def test_non_property_annotation_return_type_numpy(self):
+        """Example of a class function trying to use `type` as return
+        documentation in a numpy style docstring
+        """
+        func_node, node = astroid.extract_node("""
+        class Foo(object):
+            def foo(self) -> int: #@
+                '''int: docstring ...
+
+                Raises
+                ------
+                RuntimeError
+                    Always
+                '''
+                raise RuntimeError()
+                return 10 #@
+        """)
+        with self.assertAddsMessages(
+            Message(
+                msg_id='missing-return-doc',
+                node=func_node),
+        ):
+            self.checker.visit_return(node)
+
     def test_ignores_return_in_abstract_method_sphinx(self):
         """Example of an abstract method documenting the return type that an
         implementation should return.
diff --git a/pylint/test/extensions/test_check_return_docs.py b/pylint/test/extensions/test_check_return_docs.py
index f2c930328..951ac0be3 100644
--- a/pylint/test/extensions/test_check_return_docs.py
+++ b/pylint/test/extensions/test_check_return_docs.py
@@ -66,6 +66,33 @@ class TestDocstringCheckerReturn(CheckerTestCase):
                 Message(msg_id='missing-return-type-doc', node=node)):
             self.checker.visit_return(return_node)
 
+    def test_sphinx_returns_annotations(self):
+        node = astroid.extract_node('''
+        def my_func(self) -> bool:
+            """This is a docstring.
+
+            :returns: Always False
+            """
+            return False
+        ''')
+        return_node = node.body[0]
+        with self.assertNoMessages():
+            self.checker.visit_return(return_node)
+
+    def test_sphinx_missing_return_type_with_annotations(self):
+        node = astroid.extract_node('''
+           def my_func(self) -> bool:
+               """This is a docstring.
+
+               :returns: Always False
+               """
+               return False
+           ''')
+        return_node = node.body[0]
+        with self.assertNoMessages():
+            self.checker.visit_return(return_node)
+
+
     def test_warn_partial_sphinx_returns_type(self):
         node = astroid.extract_node('''
         def my_func(self):