Support optional ~ or ! prefix for docstring types

3 files changed, 63 insertions, 11 deletions

diff --git a/pylint/extensions/_check_docs_utils.py b/pylint/extensions/_check_docs_utils.py
index 4499f5157..2f45e6a4c 100644
--- a/pylint/extensions/_check_docs_utils.py
+++ b/pylint/extensions/_check_docs_utils.py
@@ -102,7 +102,7 @@ def returns_something(return_node):
 def _get_raise_target(node):
     if isinstance(node.exc, astroid.Call):
         func = node.exc.func
-        if isinstance(func, astroid.Name) or isinstance(func, astroid.Attribute):
+        if isinstance(func, (astroid.Name, astroid.Attribute)):
             return utils.safe_infer(func)
     return None
 
@@ -229,7 +229,10 @@ class Docstring:
 
 
 class SphinxDocstring(Docstring):
-    re_type = r"[\w\.]+"
+    re_type = r"""
+        [~!]?                # Optional link style prefix
+        \w(?:\w|\.[^\.])*    # Valid python name
+        """
 
     re_simple_container_type = r"""
         {type}                        # a container type
@@ -294,13 +297,7 @@ class SphinxDocstring(Docstring):
         except|exception
         )
         \s+                     # whitespace
-
-        (?:                     # type declaration
-        ({type})
-        \s+
-        )?
-
-        (\w(?:\w|\.[^\.])+)     # Parameter name can include '.', e.g. re.error
+        ({type})                # exception type
         \s*                     # whitespace
         :                       # final colon
         """.format(
@@ -327,7 +324,7 @@ class SphinxDocstring(Docstring):
         types = set()
 
         for match in re.finditer(self.re_raise_in_docstring, self.doc):
-            raise_type = match.group(2)
+            raise_type = match.group(1)
             types.add(raise_type)
 
         return types
diff --git a/pylint/extensions/docparams.py b/pylint/extensions/docparams.py
index c464e0d0a..771d64c04 100644
--- a/pylint/extensions/docparams.py
+++ b/pylint/extensions/docparams.py
@@ -252,6 +252,7 @@ class DocstringParameterChecker(BaseChecker):
             return
 
         expected_excs = utils.possible_exc_types(node)
+
         if not expected_excs:
             return
 
@@ -269,6 +270,7 @@ class DocstringParameterChecker(BaseChecker):
             return
 
         found_excs_full_names = doc.exceptions()
+
         # Extract just the class name, e.g. "error" from "re.error"
         found_excs_class_names = {exc.split(".")[-1] for exc in found_excs_full_names}
         missing_excs = expected_excs - found_excs_class_names
diff --git a/pylint/test/extensions/test_check_raise_docs.py b/pylint/test/extensions/test_check_raise_docs.py
index 5085b0b24..64ffe5b26 100644
--- a/pylint/test/extensions/test_check_raise_docs.py
+++ b/pylint/test/extensions/test_check_raise_docs.py
@@ -156,6 +156,23 @@ class TestDocstringCheckerRaise(CheckerTestCase):
         with self.assertNoMessages():
             self.checker.visit_raise(raise_node)
 
+    @set_config(accept_no_raise_doc=False)
+    def test_google_raises_with_prefix(self):
+        code_snippet = '''
+        def my_func(self):
+            """This is a google docstring.
+
+            Raises:
+                {prefix}re.error: Sometimes
+            """
+            import re
+            raise re.error('hi') #@
+        '''
+        for prefix in ["~", "!"]:
+            raise_node = astroid.extract_node(code_snippet.format(prefix=prefix))
+            with self.assertNoMessages():
+                self.checker.visit_raise(raise_node)
+
     def test_find_missing_numpy_raises(self):
         node = astroid.extract_node('''
         def my_func(self):
@@ -510,6 +527,24 @@ class TestDocstringCheckerRaise(CheckerTestCase):
         with self.assertNoMessages():
             self.checker.visit_raise(raise_node)
 
+    @set_config(accept_no_raise_doc=False)
+    def test_numpy_raises_with_prefix(self):
+        code_snippet = '''
+        def my_func(self):
+            """This is a numpy docstring.
+
+            Raises
+            ------
+            {prefix}re.error
+                Sometimes
+            """
+            import re
+            raise re.error('hi') #@
+        '''
+        for prefix in ["~", "!"]:
+            raise_node = astroid.extract_node(code_snippet.format(prefix=prefix))
+            with self.assertNoMessages():
+                self.checker.visit_raise(raise_node)
 
     def test_find_missing_sphinx_raises_infer_from_instance(self):
         raise_node = astroid.extract_node('''
@@ -562,7 +597,6 @@ class TestDocstringCheckerRaise(CheckerTestCase):
         ''')
         with self.assertNoMessages():
             self.checker.visit_raise(raise_node)
-        pass
 
     def test_find_sphinx_attr_raises_substr_exc(self):
         raise_node = astroid.extract_node('''
@@ -610,6 +644,25 @@ class TestDocstringCheckerRaise(CheckerTestCase):
         with self.assertNoMessages():
             self.checker.visit_raise(raise_node)
 
+    @set_config(accept_no_raise_doc=False)
+    def test_sphinx_raises_with_prefix(self):
+        code_snippet = '''
+        def my_func(self):
+            """This is a sphinx docstring.
+
+            :raises {prefix}re.error: Sometimes
+            """
+            import re
+            raise re.error('hi') #@
+        '''
+        for prefix in ["~", "!"]:
+            raise_node = astroid.extract_node(code_snippet.format(prefix=prefix))
+            with self.assertNoMessages():
+                self.checker.visit_raise(raise_node)
+
+
+        with self.assertNoMessages():
+            self.checker.visit_raise(raise_node)
 
     def test_ignores_raise_uninferable(self):
         raise_node = astroid.extract_node('''