TST: Allow for multiple variables on the same line in docstring validation (#28811)

Author: ChiefMilesEdgeworth

pandas/core/series.py

@@ -2076,12 +2076,12 @@ def idxmin(self, axis=0, skipna=True, *args, **kwargs):
 
         Parameters
         ----------
-        skipna : bool, default True
-            Exclude NA/null values. If the entire Series is NA, the result
-            will be NA.
         axis : int, default 0
             For compatibility with DataFrame.idxmin. Redundant for application
             on Series.
+        skipna : bool, default True
+            Exclude NA/null values. If the entire Series is NA, the result
+            will be NA.
         *args, **kwargs
             Additional keywords have no effect but might be accepted
             for compatibility with NumPy.
@@ -2146,12 +2146,12 @@ def idxmax(self, axis=0, skipna=True, *args, **kwargs):
 
         Parameters
         ----------
-        skipna : bool, default True
-            Exclude NA/null values. If the entire Series is NA, the result
-            will be NA.
         axis : int, default 0
             For compatibility with DataFrame.idxmax. Redundant for application
             on Series.
+        skipna : bool, default True
+            Exclude NA/null values. If the entire Series is NA, the result
+            will be NA.
         *args, **kwargs
             Additional keywords have no effect but might be accepted
             for compatibility with NumPy.

scripts/tests/test_validate_docstrings.py

@@ -39,6 +39,21 @@ def plot(self, kind, color="blue", **kwargs):
         """
         pass
 
+    def swap(self, arr, i, j, *args, **kwargs):
+        """
+        Swap two indicies on an array.
+
+        Parameters
+        ----------
+        arr : list
+            The list having indexes swapped.
+        i, j : int
+            The indexes being swapped.
+        *args, **kwargs
+            Extraneous parameters are being permitted.
+        """
+        pass
+
     def sample(self):
         """
         Generate and return a random number.
@@ -256,6 +271,21 @@ def say_hello():
         else:
             return None
 
+    def multiple_variables_on_one_line(self, matrix, a, b, i, j):
+        """
+        Swap two values in a matrix.
+
+        Parameters
+        ----------
+        matrix : list of list
+            A double list that represents a matrix.
+        a, b : int
+            The indicies of the first value.
+        i, j : int
+            The indicies of the second value.
+        """
+        pass
+
 
 class BadGenericDocStrings:
     """Everything here has a bad docstring
@@ -634,6 +664,17 @@ def list_incorrect_parameter_type(self, kind):
         """
         pass
 
+    def bad_parameter_spacing(self, a, b):
+        """
+        The parameters on the same line have an extra space between them.
+
+        Parameters
+        ----------
+        a,  b : int
+            Foo bar baz.
+        """
+        pass
+
 
 class BadReturns:
     def return_not_documented(self):
@@ -827,6 +868,7 @@ def test_good_class(self, capsys):
         "func",
         [
             "plot",
+            "swap",
             "sample",
             "random_letters",
             "sample_values",
@@ -837,6 +879,7 @@ def test_good_class(self, capsys):
             "good_imports",
             "no_returns",
             "empty_returns",
+            "multiple_variables_on_one_line",
         ],
     )
     def test_good_functions(self, capsys, func):
@@ -1002,6 +1045,11 @@ def test_bad_generic_functions(self, capsys, func):
                 "list_incorrect_parameter_type",
                 ('Parameter "kind" type should use "str" instead of "string"',),
             ),
+            (
+                "BadParameters",
+                "bad_parameter_spacing",
+                ("Parameters {b} not documented", "Unknown parameters { b}"),
+            ),
             pytest.param(
                 "BadParameters",
                 "blank_lines",

scripts/validate_docstrings.py

@@ -422,10 +422,11 @@ def needs_summary(self):
 
     @property
     def doc_parameters(self):
-        return collections.OrderedDict(
-            (name, (type_, "".join(desc)))
-            for name, type_, desc in self.doc["Parameters"]
-        )
+        parameters = collections.OrderedDict()
+        for names, type_, desc in self.doc["Parameters"]:
+            for name in names.split(", "):
+                parameters[name] = (type_, "".join(desc))
+        return parameters
 
     @property
     def signature_parameters(self):