Backport PR matplotlib#25327: Fix doc-string issues identified by velin

Author: timhoffm

lib/matplotlib/backend_bases.py

@@ -311,9 +311,11 @@ def draw_gouraud_triangles(self, gc, triangles_array, colors_array,
 
         Parameters
         ----------
-        points : (N, 3, 2) array-like
+        gc : `.GraphicsContextBase`
+            The graphics context.
+        triangles_array : (N, 3, 2) array-like
             Array of *N* (x, y) points for the triangles.
-        colors : (N, 3, 4) array-like
+        colors_array : (N, 3, 4) array-like
             Array of *N* RGBA colors for each point of the triangles.
         transform : `matplotlib.transforms.Transform`
             An affine transform to apply to the points.
@@ -609,6 +611,8 @@ def _draw_text_as_path(self, gc, x, y, s, prop, angle, ismath):
 
         Parameters
         ----------
+        gc : `.GraphicsContextBase`
+            The graphics context.
         x : float
             The x location of the text in display coords.
         y : float

lib/matplotlib/backend_managers.py

@@ -238,10 +238,8 @@ def add_tool(self, name, tool, *args, **kwargs):
         tool : type
             Class of the tool to be added.  A subclass will be used
             instead if one was registered for the current canvas class.
-
-        Notes
-        -----
-        args and kwargs get passed directly to the tools constructor.
+        *args, **kwargs
+            Passed to the *tool*'s constructor.
 
         See Also
         --------

lib/matplotlib/colorbar.py

@@ -1003,7 +1003,7 @@ def _set_scale(self, scale, **kwargs):
 
         Parameters
         ----------
-        value : {"linear", "log", "symlog", "logit", ...} or `.ScaleBase`
+        scale : {"linear", "log", "symlog", "logit", ...} or `.ScaleBase`
             The axis scale type to apply.
 
         **kwargs

lib/matplotlib/colors.py

@@ -1321,7 +1321,7 @@ def __call__(self, value, clip=None):
         ----------
         value
             Data to normalize.
-        clip : bool
+        clip : bool, optional
             If ``None``, defaults to ``self.clip`` (which defaults to
             ``False``).
 
@@ -1456,7 +1456,7 @@ def autoscale_None(self, A):
 
     def __call__(self, value, clip=None):
         """
-        Map value to the interval [0, 1]. The clip argument is unused.
+        Map value to the interval [0, 1]. The *clip* argument is unused.
         """
         result, is_scalar = self.process_value(value)
         self.autoscale_None(result)  # sets self.vmin, self.vmax if None
@@ -1505,6 +1505,10 @@ def __init__(self, vcenter=0, halfrange=None, clip=False):
             *vcenter* + *halfrange* is ``1.0`` in the normalization.
             Defaults to the largest absolute difference to *vcenter* for
             the values in the dataset.
+        clip : bool, default: False
+            If ``True`` values falling outside the range ``[vmin, vmax]``,
+            are mapped to 0 or 1, whichever is closer, and masked values are
+            set to 1.  If ``False`` masked values remain masked.
 
         Examples
         --------
@@ -2405,7 +2409,8 @@ def shade(self, data, cmap, norm=None, blend_mode='overlay', vmin=None,
             full illumination or shadow (and clipping any values that move
             beyond 0 or 1). Note that this is not visually or mathematically
             the same as vertical exaggeration.
-        Additional kwargs are passed on to the *blend_mode* function.
+        **kwargs
+            Additional kwargs are passed on to the *blend_mode* function.
 
         Returns
         -------
@@ -2466,7 +2471,8 @@ def shade_rgb(self, rgb, elevation, fraction=1., blend_mode='hsv',
             The x-spacing (columns) of the input *elevation* grid.
         dy : number, optional
             The y-spacing (rows) of the input *elevation* grid.
-        Additional kwargs are passed on to the *blend_mode* function.
+        **kwargs
+            Additional kwargs are passed on to the *blend_mode* function.
 
         Returns
         -------

lib/matplotlib/figure.py

@@ -936,7 +936,7 @@ def clear(self, keep_observers=False):
 
         Parameters
         ----------
-        keep_observers: bool, default: False
+        keep_observers : bool, default: False
             Set *keep_observers* to True if, for example,
             a gui widget is tracking the Axes in the figure.
         """
@@ -976,7 +976,7 @@ def clf(self, keep_observers=False):
 
         Parameters
         ----------
-        keep_observers: bool, default: False
+        keep_observers : bool, default: False
             Set *keep_observers* to True if, for example,
             a gui widget is tracking the Axes in the figure.
         """

lib/matplotlib/gridspec.py

@@ -447,6 +447,10 @@ def tight_layout(self, figure, renderer=None,
 
         Parameters
         ----------
+        figure : `.Figure`
+            The figure.
+        renderer :  `.RendererBase` subclass, optional
+            The renderer to be used.
         pad : float
             Padding between the figure edge and the edges of subplots, as a
             fraction of the font-size.

lib/matplotlib/image.py

@@ -1048,8 +1048,10 @@ def __init__(self, ax, *, interpolation='nearest', **kwargs):
         """
         Parameters
         ----------
+        ax : `~.axes.Axes`
+            The axes the image will belong to.
         interpolation : {'nearest', 'bilinear'}, default: 'nearest'
-
+            The interpolation scheme used in the resampling.
         **kwargs
             All other keyword arguments are identical to those of `.AxesImage`.
         """

lib/matplotlib/layout_engine.py

@@ -167,7 +167,10 @@ def execute(self, fig):
         ----------
         fig : `.Figure` to perform layout on.
 
-        See also: `.figure.Figure.tight_layout` and `.pyplot.tight_layout`.
+        See Also
+        --------
+        .figure.Figure.tight_layout
+        .pyplot.tight_layout
         """
         info = self._params
         renderer = fig._get_renderer()

lib/matplotlib/text.py

@@ -1626,6 +1626,9 @@ def draggable(self, state=None, use_blit=False):
         state : bool or None
             - True or False: set the draggability.
             - None: toggle the draggability.
+        use_blit : bool, default: False
+            Use blitting for faster image composition. For details see
+            :ref:`func-animation`.
 
         Returns
         -------

lib/matplotlib/widgets.py

@@ -2512,7 +2512,7 @@ def remove_state(self, state):
 
         Parameters
         ----------
-        value : str
+        state : str
             Must be a supported state of the selector. See the
             `state_modifier_keys` parameters for details.