Require ``\`` for asterisks in Sphinx-style parameter docstrings (#5464)

Co-authored-by: Jacob Walls <jacobtylerwalls@gmail.com>
Co-authored-by: Pierre Sassoulas <pierre.sassoulas@gmail.com>

5 files changed, 76 insertions, 21 deletions

diff --git a/ChangeLog b/ChangeLog
index b3292e170..221c1a249 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -39,6 +39,11 @@ Release date: TBA
 
   Closes #5437
 
+* Fixed handling of Sphinx-style parameter docstrings with asterisks. These
+  should be escaped with by prepending a "\".
+
+  Closes #5406
+
 * Add ``endLine`` and ``endColumn`` keys to output of ``JSONReporter``.
 
   Closes #5380
diff --git a/pylint/extensions/_check_docs_utils.py b/pylint/extensions/_check_docs_utils.py
index 5227e74ae..5b63eeb97 100644
--- a/pylint/extensions/_check_docs_utils.py
+++ b/pylint/extensions/_check_docs_utils.py
@@ -280,9 +280,9 @@ class SphinxDocstring(Docstring):
         \s+
         )?
 
-        (\*{{0,2}}\w+)          # Parameter name with potential asterisks
-        \s*                     # whitespace
-        :                       # final colon
+        ((\\\*{{1,2}}\w+)|(\w+))  # Parameter name with potential asterisks
+        \s*                       # whitespace
+        :                         # final colon
         """
     re_param_in_docstring = re.compile(re_param_raw, re.X | re.S)
 
@@ -377,6 +377,8 @@ class SphinxDocstring(Docstring):
 
         for match in re.finditer(self.re_param_in_docstring, self.doc):
             name = match.group(2)
+            # Remove escape characters necessary for asterisks
+            name = name.replace("\\", "")
             params_with_doc.add(name)
             param_type = match.group(1)
             if param_type is not None:
diff --git a/pylint/reporters/text.py b/pylint/reporters/text.py
index 190bf3bb5..ff9fac3ba 100644
--- a/pylint/reporters/text.py
+++ b/pylint/reporters/text.py
@@ -140,7 +140,7 @@ def colorize_ansi(
     style: Optional[str] = None,
     **kwargs: Optional[str],
 ) -> str:
-    """colorize message by wrapping it with ansi escape codes
+    r"""colorize message by wrapping it with ansi escape codes
 
     :param msg: the message string to colorize
 
@@ -149,7 +149,7 @@ def colorize_ansi(
 
     :param style: the message's style elements, this will be deprecated
 
-    :param **kwargs: used to accept `color` parameter while it is being deprecated
+    :param \**kwargs: used to accept `color` parameter while it is being deprecated
 
     :return: the ansi escaped string
     """
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
index e7b5310d9..0ec15b234 100644
--- a/tests/functional/ext/docparams/parameter/missing_param_doc_required_Sphinx.py
+++ b/tests/functional/ext/docparams/parameter/missing_param_doc_required_Sphinx.py
@@ -158,6 +158,7 @@ def test_warns_missing_args_sphinx(  # [missing-param-doc, inconsistent-return-s
 
     :param named_arg: Returned
     :type named_arg: object
+
     :returns: Maybe named_arg
     :rtype: object or None
     """
@@ -172,6 +173,7 @@ def test_warns_missing_kwargs_sphinx(  # [missing-param-doc, inconsistent-return
 
     :param named_arg: Returned
     :type named_arg: object
+
     :returns: Maybe named_arg
     :rtype: object or None
     """
@@ -179,14 +181,16 @@ def test_warns_missing_kwargs_sphinx(  # [missing-param-doc, inconsistent-return
         return named_arg
 
 
-def test_finds_args_without_type_sphinx(  # [inconsistent-return-statements]
+def test_finds_args_without_type_sphinx(  # [missing-param-doc, 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
     """
@@ -194,14 +198,54 @@ def test_finds_args_without_type_sphinx(  # [inconsistent-return-statements]
         return named_arg
 
 
-def test_finds_kwargs_without_type_sphinx(  # [inconsistent-return-statements]
+def test_finds_kwargs_without_type_sphinx(  # [missing-param-doc, 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
+
+
+def test_finds_args_without_type_sphinx(  # [inconsistent-return-statements]
+    named_arg, *args
+):
+    r"""The Sphinx docstring
+    In Sphinx docstrings asteriks should be escaped.
+    See https://github.com/PyCQA/pylint/issues/5406
+
+    :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
+):
+    r"""The Sphinx docstring
+    In Sphinx docstrings asteriks should be escaped.
+    See https://github.com/PyCQA/pylint/issues/5406
+
+    :param named_arg: Returned
+    :type named_arg: object
+
+    :param \**kwargs: Keyword arguments
+
     :returns: Maybe named_arg
     :rtype: object or None
     """
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
index 9eb927663..7745f7619 100644
--- a/tests/functional/ext/docparams/parameter/missing_param_doc_required_Sphinx.txt
+++ b/tests/functional/ext/docparams/parameter/missing_param_doc_required_Sphinx.txt
@@ -17,17 +17,21 @@ missing-type-doc:131:0:151:12:ClassFoo:"""x, y"" missing in parameter type docum
 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
+inconsistent-return-statements:154:0:166: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:166:24:test_warns_missing_args_sphinx:"""*args"" missing in parameter documentation":UNDEFINED
+inconsistent-return-statements:169:0:181: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:169:0:181:24:test_warns_missing_kwargs_sphinx:"""**kwargs"" missing in parameter documentation":UNDEFINED
+inconsistent-return-statements:184:0:198:24:test_finds_args_without_type_sphinx:Either all return statements in a function should return an expression, or none of them should.:UNDEFINED
+missing-param-doc:184:0:198:24:test_finds_args_without_type_sphinx:"""*args"" missing in parameter documentation":UNDEFINED
+inconsistent-return-statements:201:0:215: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-param-doc:201:0:215:24:test_finds_kwargs_without_type_sphinx:"""**kwargs"" missing in parameter documentation":UNDEFINED
+inconsistent-return-statements:218:0:234: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:237:0:253: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:263:4:268:17:Foo.foo:"""AttributeError"" not documented as being raised":UNDEFINED
+unreachable:289:8:289:17:Foo.foo:Unreachable code:UNDEFINED
+missing-param-doc:292:4:297:30:Foo.foo:"""value"" missing in parameter documentation":UNDEFINED
+missing-raises-doc:292:4:297:30:Foo.foo:"""AttributeError"" not documented as being raised":UNDEFINED
+missing-type-doc:292:4:297:30:Foo.foo:"""value"" missing in parameter type documentation":UNDEFINED
+unreachable:328:8:328:17:Foo.foo:Unreachable code:UNDEFINED
+useless-param-doc:332:4:346:12:Foo.test_useless_docs_ignored_argument_names_sphinx:"""_, _ignored"" useless ignored parameter documentation":UNDEFINED
+useless-type-doc:332:4:346:12:Foo.test_useless_docs_ignored_argument_names_sphinx:"""_"" useless ignored parameter type documentation":UNDEFINED