Support combined NumPyDoc params (#41)

NumPyDoc allows joining multiple parameters with shared type on one
line. This pattern is quite common in the ecosystem so support this.

Author: lagru

src/docstub/_docstrings.py

@@ -532,6 +532,32 @@ def _match_import(self, qualname, *, meta):
         return matched_qualname
 
 
+def _uncombine_numpydoc_params(params):
+    """Split combined NumPyDoc parameters.
+
+    NumPyDoc allows joining multiple parameters with shared type on one line.
+    This function helps with iterating them one-by-one regardless.
+
+    Parameters
+    ----------
+    params : list[numpydoc.docsrape.Parameter]
+
+    Yields
+    ------
+    param : numpydoc.docscrape.Parameter
+    """
+    for param in params:
+        if "," in param.name:
+            # Multiple parameters on one line, split and yield separately
+            names = [p.strip() for p in param.name.split(",")]
+            for name in names:
+                # Uncombined parameter re-uses shared type and description
+                uncombined = npds.Parameter(name=name, type=param.type, desc=param.desc)
+                yield uncombined
+        else:
+            yield param
+
+
 class DocstringAnnotations:
     """Collect annotations in a given docstring.
 
@@ -793,7 +819,10 @@ def _section_annotations(self, name):
             Entries without annotations fall back to :class:`_typeshed.Incomplete`.
         """
         annotated_params = {}
-        for param in self.np_docstring[name]:
+
+        params = self.np_docstring[name]
+        params = list(_uncombine_numpydoc_params(params))
+        for param in params:
             param = self._handle_missing_whitespace(param)  # noqa: PLW2901
 
             if param.name in annotated_params:

tests/test_docstrings.py

@@ -430,3 +430,28 @@ def test_missing_whitespace(self, capsys):
         assert annotations.parameters["a"].value == "int"
         captured = capsys.readouterr()
         assert "Possibly missing whitespace" in captured.out
+
+    def test_combined_numpydoc_params(self):
+        docstring = dedent(
+            """
+            Parameters
+            ----------
+            a, b, c : bool
+            d, e :
+            """
+        )
+        transformer = DoctypeTransformer()
+        annotations = DocstringAnnotations(docstring, transformer=transformer)
+        assert len(annotations.parameters) == 5
+        assert annotations.parameters["a"].value == "bool"
+        assert annotations.parameters["b"].value == "bool"
+        assert annotations.parameters["c"].value == "bool"
+
+        assert annotations.parameters["d"].value == "Incomplete"
+        assert annotations.parameters["e"].value == "Incomplete"
+        assert annotations.parameters["d"].imports == {
+            KnownImport.typeshed_Incomplete()
+        }
+        assert annotations.parameters["e"].imports == {
+            KnownImport.typeshed_Incomplete()
+        }