Fix and refactors for docparams extension

pylint/extensions/_check_docs_utils.py

@@ -247,7 +247,7 @@ class SphinxDocstring(Docstring):
 
     re_multiple_simple_type = r"""
         (?:{container_type}|{type})
-        (?:(?:\s+(?:of|or)\s+|\s*,\s*)(?:{container_type}|{type}))*
+        (?:(?:\s+(?:of|or)\s+|\s*,\s*|\s+\|\s+)(?:{container_type}|{type}))*
     """.format(
         type=re_type, container_type=re_simple_container_type
     )
@@ -449,7 +449,7 @@ class GoogleDocstring(Docstring):
 
     re_multiple_type = r"""
         (?:{container_type}|{type}|{xref})
-        (?:(?:\s+(?:of|or)\s+|\s*,\s*)(?:{container_type}|{type}|{xref}))*
+        (?:(?:\s+(?:of|or)\s+|\s*,\s*|\s+\|\s+)(?:{container_type}|{type}|{xref}))*
     """.format(
         type=re_type, xref=re_xref, container_type=re_container_type
     )
@@ -728,22 +728,25 @@ class NumpyDocstring(GoogleDocstring):
         re.X | re.S | re.M,
     )
 
-    re_default_value = r"""((['"]\w+\s*['"])|(True)|(False)|(None))"""
+    re_default_value = r"""((['"]\w+\s*['"])|(\d+)|(True)|(False)|(None))"""
 
     re_param_line = re.compile(
         rf"""
-        \s*  (\*{{0,2}}\w+)(\s?(:|\n))              # identifier with potential asterisks
+        \s*  (?P<param_name>\*{{0,2}}\w+)(\s?(:|\n)) # identifier with potential asterisks
         \s*
-        (
+        (?P<param_type>
          (
           ({GoogleDocstring.re_multiple_type})      # default type declaration
           (,\s+optional)?                           # optional 'optional' indication
          )?
          (
           {{({re_default_value},?\s*)+}}            # set of default values
          )?
-        \n)?
-        \s* (.*)                                    # optional description
+         (?:$|\n)
+        )?
+        (
+         \s* (?P<param_desc>.*)                     # optional description
+        )?
     """,
         re.X | re.S,
     )
@@ -794,15 +797,22 @@ def match_param_docs(self) -> tuple[set[str], set[str]]:
                 continue
 
             # check if parameter has description only
-            re_only_desc = re.match(r"\s*  (\*{0,2}\w+)\s*:?\n", entry)
+            re_only_desc = re.match(r"\s*(\*{0,2}\w+)\s*:?\n\s*\w*$", entry)
             if re_only_desc:
-                param_name = match.group(1)
-                param_desc = match.group(2)
+                param_name = match.group("param_name")
+                param_desc = match.group("param_type")
                 param_type = None
             else:
-                param_name = match.group(1)
-                param_type = match.group(3)
-                param_desc = match.group(4)
+                param_name = match.group("param_name")
+                param_type = match.group("param_type")
+                param_desc = match.group("param_desc")
+                # The re_param_line pattern needs to match multi-line which removes the ability
+                # to match a single line description like 'arg : a number type.'
+                # We are not trying to determine whether 'a number type' is correct typing
+                # but we do accept it as typing as it is in the place where typing
+                # should be
+                if param_type is None and re.match(r"\s*(\*{0,2}\w+)\s*:.+$", entry):
+                    param_type = param_desc
 
             if param_type:
                 params_with_type.add(param_name)

tests/functional/ext/docparams/docparams.py

@@ -13,7 +13,7 @@ def _private_func2(param1):  # [missing-yield-doc, missing-yield-type-doc]
 
 def _private_func3(param1):  # [missing-raises-doc]
     """This is a test docstring without raises"""
-    raise Exception('Example')
+    raise Exception("Example")
 
 
 def public_func1(param1):  # [missing-any-param-doc]
@@ -33,7 +33,7 @@ async def _async_private_func2(param1):  # [missing-yield-doc, missing-yield-typ
 
 async def _async_private_func3(param1):  # [missing-raises-doc]
     """This is a test docstring without raises"""
-    raise Exception('Example')
+    raise Exception("Example")
 
 
 async def async_public_func1(param1):  # [missing-any-param-doc]

tests/functional/ext/docparams/parameter/missing_param_doc_required_Numpy.py

@@ -392,6 +392,7 @@ def test_ignores_optional_specifier_numpy(param, param2="all"):
     """
     return param, param2
 
+
 def test_with_list_of_default_values(arg, option, option2):
     """Reported in https://github.com/PyCQA/pylint/issues/4035.
 
@@ -406,3 +407,17 @@ def test_with_list_of_default_values(arg, option, option2):
 
     """
     return arg, option, option2
+
+
+def test_with_descriptions_instead_of_typing(arg, option):
+    """We choose to accept description in place of typing as well.
+
+    See: https://github.com/PyCQA/pylint/pull/7398.
+
+    Parameters
+    ----------
+    arg : a number type.
+    option : {"y", "n"}
+        Do I do it?
+    """
+    return arg, option