Less ACCEPTS, more numpydoc.

anntzer · anntzer · commit 50fc4c83a99d · 2018-09-24T07:11:10.000+02:00
diff --git a/doc/api/next_api_changes/2018-09-22-AL.rst b/doc/api/next_api_changes/2018-09-22-AL.rst
@@ -0,0 +1,4 @@
+Additional positional arguments to `Axis.set_ticklabels`
+````````````````````````````````````````````````````````
+Passing positional arguments to `Axis.set_ticklabels` beyond `ticklabels`
+itself has no effect, and support for them is deprecated.
diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py
@@ -1227,7 +1227,9 @@ def get_valid_values(self, attr):
         # Much faster than list(inspect.signature(func).parameters)[1],
         # although barely relevant wrt. matplotlib's total import time.
         param_name = func.__code__.co_varnames[1]
-        match = re.search("(?m)^ *{} : (.+)".format(param_name), docstring)
+        # We could set the presence * based on whether the parameter is a
+        # varargs (it can't be a varkwargs) but it's not really worth the it.
+        match = re.search("(?m)^ *\*?{} : (.+)".format(param_name), docstring)
         if match:
             return match.group(1)
 
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -4881,7 +4881,7 @@ def fill(self, *args, **kwargs):
 
         Parameters
         ----------
-        args : sequence of x, y, [color]
+        *args : sequence of x, y, [color]
             Each polygon is defined by the lists of *x* and *y* positions of
             its nodes, optionally followed by a *color* specifier. See
             :mod:`matplotlib.colors` for supported color specifiers. The
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -2248,7 +2248,7 @@ def margins(self, *margins, x=None, y=None, tight=True):
 
         Parameters
         ----------
-        args : float, optional
+        *margins : float, optional
             If a single positional argument is provided, it specifies
             both margins of the x-axis and y-axis limits. If two
             positional arguments are provided, they will be interpreted
diff --git a/lib/matplotlib/axis.py b/lib/matplotlib/axis.py
@@ -1539,9 +1539,11 @@ def convert_units(self, x):
 
     def set_units(self, u):
         """
-        set the units for axis
+        Set the units for axis.
 
-        ACCEPTS: a units tag
+        Parameters
+        ----------
+        u : units tag
         """
         pchanged = False
         if u is None:
@@ -1558,14 +1560,21 @@ def set_units(self, u):
         self.stale = True
 
     def get_units(self):
-        'return the units for axis'
+        """Return the units for axis."""
         return self.units
 
     def set_label_text(self, label, fontdict=None, **kwargs):
         """
         Set the text value of the axis label.
 
-        ACCEPTS: A string value for the label
+        Parameters
+        ----------
+        label : str
+            Text string.
+        fontdict : dict
+            Text properties.
+        **kwargs :
+            Merged into fontdict.
         """
         self.isDefault_label = False
         self.label.set_text(label)
@@ -1601,7 +1610,7 @@ def set_minor_formatter(self, formatter):
         """
         if not isinstance(formatter, mticker.Formatter):
             raise TypeError("formatter argument should be instance of "
-                    "matplotlib.ticker.Formatter")
+                            "matplotlib.ticker.Formatter")
         self.isDefault_minfmt = False
         self.minor.formatter = formatter
         formatter.set_axis(self)
@@ -1617,7 +1626,7 @@ def set_major_locator(self, locator):
         """
         if not isinstance(locator, mticker.Locator):
             raise TypeError("formatter argument should be instance of "
-                    "matplotlib.ticker.Locator")
+                            "matplotlib.ticker.Locator")
         self.isDefault_majloc = False
         self.major.locator = locator
         locator.set_axis(self)
@@ -1633,7 +1642,7 @@ def set_minor_locator(self, locator):
         """
         if not isinstance(locator, mticker.Locator):
             raise TypeError("formatter argument should be instance of "
-                    "matplotlib.ticker.Locator")
+                            "matplotlib.ticker.Locator")
         self.isDefault_minloc = False
         self.minor.locator = locator
         locator.set_axis(self)
@@ -1651,21 +1660,29 @@ def set_pickradius(self, pickradius):
 
     def set_ticklabels(self, ticklabels, *args, minor=False, **kwargs):
         """
-        Set the text values of the tick labels. Return a list of Text
-        instances.  Use *kwarg* *minor=True* to select minor ticks.
-        All other kwargs are used to update the text object properties.
-        As for get_ticklabels, label1 (left or bottom) is
-        affected for a given tick only if its label1On attribute
-        is True, and similarly for label2.  The list of returned
-        label text objects consists of all such label1 objects followed
-        by all such label2 objects.
+        Set the text values of the tick labels.
 
-        The input *ticklabels* is assumed to match the set of
-        tick locations, regardless of the state of label1On and
-        label2On.
+        Parameters
+        ----------
+        ticklabels : sequence of str or of `Text`\s
+            List of texts for tick labels; must include values for non-visible
+            labels.
+        minor : bool
+            If True, set minor ticks instead of major ticks.
+        **kwargs
+            Text properties.
 
-        ACCEPTS: sequence of strings or Text objects
-        """
+        Returns
+        -------
+        labels : list of `Text`\s
+            For each tick, includes ``tick.label1`` if it is visible, then
+            ``tick.label2`` if it is visible, in that order.
+        """
+        if args:
+            cbook.warn_deprecated(
+                "3.1", "Additional positional arguments to set_ticklabels are "
+                "ignored, and deprecated since Matplotlib 3.1; passing them "
+                "will raise a TypeError in Matplotlib 3.3.")
         get_labels = []
         for t in ticklabels:
             # try calling get_text() to check whether it is Text object
@@ -1705,7 +1722,10 @@ def set_ticks(self, ticks, minor=False):
         """
         Set the locations of the tick marks from sequence ticks
 
-        ACCEPTS: sequence of floats
+        Parameters
+        ----------
+        ticks : sequence of floats
+        minor : bool
         """
         # XXX if the user changes units, the information will be lost here
         ticks = self.convert_units(ticks)
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -979,15 +979,21 @@ def set_figwidth(self, val, forward=True):
         """
         Set the width of the figure in inches.
 
-        .. ACCEPTS: float
+        Parameters
+        ----------
+        val : float
+        forward : bool
         """
         self.set_size_inches(val, self.get_figheight(), forward=forward)
 
     def set_figheight(self, val, forward=True):
         """
         Set the height of the figure in inches.
 
-        .. ACCEPTS: float
+        Parameters
+        ----------
+        val : float
+        forward : bool
         """
         self.set_size_inches(self.get_figwidth(), val, forward=forward)
 
diff --git a/lib/matplotlib/lines.py b/lib/matplotlib/lines.py
@@ -650,7 +650,9 @@ def set_data(self, *args):
         """
         Set the x and y data.
 
-        ACCEPTS: 2D array (rows are x, y) or two 1D arrays
+        Parameters
+        ----------
+        *args : (N, 2) array or two 1D arrays
         """
         if len(args) == 1:
             x, y = args[0]
diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py
@@ -337,9 +337,11 @@ def set_alpha(self, alpha):
 
     def set_linewidth(self, w):
         """
-        Set the patch linewidth in points
+        Set the patch linewidth in points.
 
-        ACCEPTS: float or None for default
+        Parameters
+        ----------
+        w : float or None
         """
         if w is None:
             w = mpl.rcParams['patch.linewidth']
@@ -2516,7 +2518,6 @@ def set_boxstyle(self, boxstyle=None, **kw):
         %(AvailableBoxstyles)s
 
         ACCEPTS: %(ListBoxstyles)s
-
         """
         if boxstyle is None:
             return BoxStyle.pprint_styles()
diff --git a/lib/matplotlib/tests/test_artist.py b/lib/matplotlib/tests/test_artist.py
@@ -262,6 +262,7 @@ def test_None_zorder():
     ('ACCEPTS: Some description.', 'Some description. '),
     ('.. ACCEPTS: Some description.', 'Some description. '),
     ('arg : int', 'int'),
+    ('*arg : int', 'int'),
     ('arg : int\nACCEPTS: Something else.', 'Something else. '),
 ])
 def test_artist_inspector_get_valid_values(accept_clause, expected):
diff --git a/lib/mpl_toolkits/axes_grid1/axes_divider.py b/lib/mpl_toolkits/axes_grid1/axes_divider.py
@@ -361,7 +361,7 @@ def __init__(self, fig, *args, horizontal=None, vertical=None,
         Parameters
         ----------
         fig : :class:`matplotlib.figure.Figure`
-        args : tuple (*numRows*, *numCols*, *plotNum*)
+        *args : tuple (*numRows*, *numCols*, *plotNum*)
             The array of subplots in the figure has dimensions *numRows*,
             *numCols*, and *plotNum* is the number of the subplot
             being created.  *plotNum* starts at 1 in the upper left
