BUG: Partial fix for docstring validation for parameters

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

@@ -1,3 +1,4 @@
+from functools import wraps
 import io
 import random
 import string
@@ -12,6 +13,39 @@
 validate_one = validate_docstrings.validate_one
 
 
+class Decorators:
+    @staticmethod
+    def good_decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            """
+            Wrapper function.
+
+            This docstring should be hidden, and not used during validation.
+            Using the @wraps decorator should allow validation to get the
+            signature of the wrapped function when comparing against the
+            docstring.
+            """
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    @staticmethod
+    def missing_wraps(func):
+        def wrapper(*args):
+            """
+            Wrapper function.
+
+            The signature of this wrapper should override the underlying
+            function. So, we should see errors regarding the parameters,
+            like expecting documentation for *args and **kwargs and missing
+            documentation for the underlying signature.
+            """
+            return func(*args)
+
+        return wrapper
+
+
 class GoodDocStrings:
     """
     Collection of good doc strings.
@@ -53,6 +87,21 @@ def sample(self):
         """
         return random.random()
 
+    @Decorators.good_decorator
+    def decorated_sample(self):
+        """
+        Generate and return a random number.
+
+        The value is sampled from a continuous uniform distribution between
+        0 and 1.
+
+        Returns
+        -------
+        float
+            Random number generated.
+        """
+        return random.random()
+
     def random_letters(self):
         """
         Generate and return a sequence of random letters.
@@ -634,6 +683,19 @@ def list_incorrect_parameter_type(self, kind):
         """
         pass
 
+    @Decorators.missing_wraps
+    def bad_decorator(self, kind: bool):
+        """
+        The decorator is missing the @wraps, and overrides the signature
+        of this method.
+
+        Parameters
+        ----------
+        kind : bool
+            Foo bar baz
+        """
+        pass
+
 
 class BadReturns:
     def return_not_documented(self):
@@ -828,6 +890,7 @@ def test_good_class(self, capsys):
         [
             "plot",
             "sample",
+            "decorated_sample",
             "random_letters",
             "sample_values",
             "head",
@@ -1002,6 +1065,7 @@ def test_bad_generic_functions(self, capsys, func):
                 "list_incorrect_parameter_type",
                 ('Parameter "kind" type should use "str" instead of "string"',),
             ),
+            ("BadParameters", "bad_decorator", ("Parameters {*args} not documented",)),
             pytest.param(
                 "BadParameters",
                 "blank_lines",

scripts/validate_docstrings.py

@@ -436,16 +436,20 @@ def signature_parameters(self):
                 # accessor classes have a signature but don't want to show this
                 return tuple()
         try:
-            sig = inspect.getfullargspec(self.obj)
+            sig = inspect.signature(self.obj)
         except (TypeError, ValueError):
             # Some objects, mainly in C extensions do not support introspection
             # of the signature
             return tuple()
-        params = sig.args
-        if sig.varargs:
-            params.append("*" + sig.varargs)
-        if sig.varkw:
-            params.append("**" + sig.varkw)
+        params = list()
+        for parameter, data in sig.parameters.items():
+            if data.kind == inspect.Parameter.VAR_POSITIONAL:
+                params.append("*" + parameter)
+            elif data.kind == inspect.Parameter.VAR_KEYWORD:
+                params.append("**" + parameter)
+            else:
+                params.append(parameter)
+
         params = tuple(params)
         if params and params[0] in ("self", "cls"):
             return params[1:]