From 54a64092f1bc8d6638bd8432566c6735fe72867d Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Sun, 9 Jun 2019 23:33:27 +0200
Subject: [PATCH] Fix pydocstyle D403 (First word of the first line should be
 properly capitalized)

---
 lib/matplotlib/__init__.py            |  2 +-
 lib/matplotlib/_constrained_layout.py | 10 ++-----
 lib/matplotlib/axis.py                | 21 ++++++-------
 lib/matplotlib/colorbar.py            |  8 ++---
 lib/matplotlib/dates.py               |  2 +-
 lib/matplotlib/image.py               | 39 ++++++++++++++----------
 lib/matplotlib/patches.py             | 43 +++++++++++++--------------
 lib/matplotlib/patheffects.py         |  2 +-
 lib/matplotlib/projections/polar.py   |  2 ++
 lib/matplotlib/ticker.py              | 36 ++++++++++------------
 10 files changed, 80 insertions(+), 85 deletions(-)

diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
index 6f99c231841b..5d31f4b9ff03 100644
--- a/lib/matplotlib/__init__.py
+++ b/lib/matplotlib/__init__.py
@@ -603,7 +603,7 @@ def get_cachedir():
 
 
 def _get_data_path():
-    'get the path to matplotlib data'
+    """Return the path to matplotlib data."""
 
     if 'MATPLOTLIBDATA' in os.environ:
         path = os.environ['MATPLOTLIBDATA']
diff --git a/lib/matplotlib/_constrained_layout.py b/lib/matplotlib/_constrained_layout.py
index 1a554275c852..484f4a67829b 100644
--- a/lib/matplotlib/_constrained_layout.py
+++ b/lib/matplotlib/_constrained_layout.py
@@ -66,10 +66,7 @@ def _in_same_row(rownum0min, rownum0max, rownumCmin, rownumCmax):
 
 
 def _axes_all_finite_sized(fig):
-    """
-    helper function to make sure all axes in the
-    figure have a finite width and height.  If not, return False
-    """
+    """Return whether all axes in the figure have a finite width and height."""
     for ax in fig.axes:
         if ax._layoutbox is not None:
             newpos = ax._poslayoutbox.get_rect()
@@ -471,10 +468,7 @@ def _align_spines(fig, gs):
 
 
 def _arrange_subplotspecs(gs, hspace=0, wspace=0):
-    """
-    arrange the subplotspec children of this gridspec, and then recursively
-    do the same of any gridspec children of those gridspecs...
-    """
+    """Recursively arrange the subplotspec children of the given gridspec."""
     sschildren = []
     for child in gs.children:
         if child._is_subplotspec_layoutbox():
diff --git a/lib/matplotlib/axis.py b/lib/matplotlib/axis.py
index 8b368c959224..a2b487da785a 100644
--- a/lib/matplotlib/axis.py
+++ b/lib/matplotlib/axis.py
@@ -326,7 +326,9 @@ def _set_artist_props(self, a):
         a.set_figure(self.figure)
 
     def get_view_interval(self):
-        'return the view Interval instance for the axis this tick is ticking'
+        """
+        Return the view limits ``(min, max)`` of the axis the tick belongs to.
+        """
         raise NotImplementedError('Derived must override')
 
     def _apply_params(self, **kw):
@@ -624,7 +626,7 @@ def update_position(self, loc):
         self.stale = True
 
     def get_view_interval(self):
-        """Return the Interval instance for this axis view limits."""
+        # docstring inherited
         return self.axes.viewLim.intervaly
 
 
@@ -839,7 +841,7 @@ def get_children(self):
                 *self.get_major_ticks(), *self.get_minor_ticks()]
 
     def cla(self):
-        'clear the current axis'
+        """Clear this axis."""
 
         self.label.set_text('')  # self.set_label_text would change isDefault_
 
@@ -971,7 +973,7 @@ def set_clip_path(self, clippath, transform=None):
         self.stale = True
 
     def get_view_interval(self):
-        """Return the Interval instance for this axis view limits."""
+        """Return the view limits ``(min, max)`` of this axis."""
         raise NotImplementedError('Derived must override')
 
     def set_view_interval(self, vmin, vmax, ignore=False):
@@ -1391,11 +1393,11 @@ def get_ticks_direction(self, minor=False):
                 [tick._tickdir for tick in self.get_major_ticks()])
 
     def _get_tick(self, major):
-        'return the default tick instance'
+        """Return the default tick instance."""
         raise NotImplementedError('derived must override')
 
     def _copy_tick_props(self, src, dest):
-        'Copy the props from src tick to dest tick'
+        """Copy the properties from *src* tick to *dest* tick."""
         if src is None or dest is None:
             return
         dest.label1.update_from(src.label1)
@@ -1502,11 +1504,10 @@ def grid(self, b=None, which='major', **kwargs):
 
     def update_units(self, data):
         """
-        introspect *data* for units converter and update the
+        Introspect *data* for units converter and update the
         axis.converter instance if necessary. Return *True*
         if *data* is registered for unit conversion.
         """
-
         converter = munits.registry.get_converter(data)
         if converter is None:
             return False
@@ -1524,8 +1525,8 @@ def update_units(self, data):
 
     def _update_axisinfo(self):
         """
-        check the axis converter for the stored units to see if the
-        axis info needs to be updated
+        Check the axis converter for the stored units to see if the
+        axis info needs to be updated.
         """
         if self.converter is None:
             return
diff --git a/lib/matplotlib/colorbar.py b/lib/matplotlib/colorbar.py
index fcd878ab515b..22fdb6801581 100644
--- a/lib/matplotlib/colorbar.py
+++ b/lib/matplotlib/colorbar.py
@@ -340,16 +340,12 @@ def set_clim(self, vmin=None, vmax=None):
 
     @cbook.deprecated("3.1", alternative="ScalarMappable.get_cmap")
     def get_cmap(self):
-        """
-        return the colormap
-        """
+        """Return the colormap."""
         return self.cmap
 
     @cbook.deprecated("3.1", alternative="ScalarMappable.get_clim")
     def get_clim(self):
-        """
-        return the min, max of the color limits for image scaling
-        """
+        """Return the min, max of the color limits for image scaling."""
         return self.norm.vmin, self.norm.vmax
 
 
diff --git a/lib/matplotlib/dates.py b/lib/matplotlib/dates.py
index ae1225d0e7c2..3c8464e3da3f 100644
--- a/lib/matplotlib/dates.py
+++ b/lib/matplotlib/dates.py
@@ -1352,7 +1352,7 @@ def set_axis(self, axis):
         self._locator.set_axis(axis)
 
     def refresh(self):
-        'Refresh internal information based on current limits.'
+        # docstring inherited
         dmin, dmax = self.viewlim_to_dt()
         self._locator = self.get_locator(dmin, dmax)
 
diff --git a/lib/matplotlib/image.py b/lib/matplotlib/image.py
index 26f0c9475769..da5d7d4cad77 100644
--- a/lib/matplotlib/image.py
+++ b/lib/matplotlib/image.py
@@ -537,10 +537,9 @@ def make_image(self, renderer, magnification=1.0, unsampled=False):
 
     def _draw_unsampled_image(self, renderer, gc):
         """
-        draw unsampled image. The renderer should support a draw_image method
+        Draw unsampled image. The renderer should support a draw_image method
         with scale parameter.
         """
-
         im, l, b, trans = self.make_image(renderer, unsampled=True)
 
         if im is None:
@@ -552,7 +551,8 @@ def _draw_unsampled_image(self, renderer, gc):
 
     def _check_unsampled_image(self, renderer):
         """
-        return True if the image is better to be drawn unsampled.
+        Return whether the image is better to be drawn unsampled.
+
         The derived class needs to override it.
         """
         return False
@@ -852,12 +852,20 @@ def _check_unsampled_image(self, renderer):
 
     def set_extent(self, extent):
         """
-        extent is data axes (left, right, bottom, top) for making image plots
+        Set the image extent.
 
-        This updates ax.dataLim, and, if autoscaling, sets viewLim
-        to tightly fit the image, regardless of dataLim.  Autoscaling
+        Parameters
+        ----------
+        extent : 4-tuple of float
+            The position and size of the image as tuple
+            ``(left, right, bottom, top)`` in data coordinates.
+
+        Notes
+        -----
+        This updates ``ax.dataLim`, and, if autoscaling, sets ``ax.viewLim``
+        to tightly fit the image, regardless of ``dataLim``.  Autoscaling
         state is not changed, so following this with ax.autoscale_view
-        will redo the autoscaling in accord with dataLim.
+        will redo the autoscaling in accord with ``dataLim``.
         """
         self._extent = xmin, xmax, ymin, ymax = extent
         corners = (xmin, ymin), (xmax, ymax)
@@ -871,7 +879,7 @@ def set_extent(self, extent):
         self.stale = True
 
     def get_extent(self):
-        """Get the image extent: left, right, bottom, top"""
+        """Return the image extent as tuple (left, right, bottom, top)."""
         if self._extent is not None:
             return self._extent
         else:
@@ -923,17 +931,18 @@ def format_cursor_data(self, data):
 class NonUniformImage(AxesImage):
     def __init__(self, ax, *, interpolation='nearest', **kwargs):
         """
-        kwargs are identical to those for AxesImage, except
-        that 'nearest' and 'bilinear' are the only supported 'interpolation'
-        options.
+        Parameters
+        ----------
+        interpolation : {'nearest', 'bilinear'}
+
+        **kwargs
+            All other keyword arguments are identical to those of `.AxesImage`.
         """
         super().__init__(ax, **kwargs)
         self.set_interpolation(interpolation)
 
     def _check_unsampled_image(self, renderer):
-        """
-        return False. Do not use unsampled image.
-        """
+        """Return False. Do not use unsampled image."""
         return False
 
     def make_image(self, renderer, magnification=1.0, unsampled=False):
@@ -1204,7 +1213,7 @@ def __init__(self, fig,
         self.magnification = 1.0
 
     def get_extent(self):
-        """Get the image extent: left, right, bottom, top"""
+        """Return the image extent as tuple (left, right, bottom, top)."""
         numrows, numcols = self.get_size()
         return (-0.5 + self.ox, numcols-0.5 + self.ox,
                 -0.5 + self.oy, numrows-0.5 + self.oy)
diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py
index 9f90f2b9796c..4b43dcb6f55d 100644
--- a/lib/matplotlib/patches.py
+++ b/lib/matplotlib/patches.py
@@ -405,7 +405,7 @@ def set_fill(self, b):
         self.stale = True
 
     def get_fill(self):
-        'return whether fill is set'
+        """Return whether the patch is filled."""
         return self._fill
 
     # Make fill a property so as to preserve the long-standing
@@ -1797,9 +1797,7 @@ class _Style:
     provides some helper functions.
     """
     def __new__(cls, stylename, **kw):
-        """
-        return the instance of the subclass with the given style name.
-        """
+        """Return the instance of the subclass with the given style name."""
 
         # The "class" should have the _style_list attribute, which is a mapping
         # of style names to style classes.
@@ -3025,8 +3023,8 @@ def connect(self, posA, posB):
 
 def _point_along_a_line(x0, y0, x1, y1, d):
     """
-    find a point along a line connecting (x0, y0) -- (x1, y1) whose
-    distance from (x0, y0) is d.
+    Return the point on the line connecting (*x0*, *y0*) -- (*x1*, *y1*) whose
+    distance from (*x0*, *y0*) is *d*.
     """
     dx, dy = x0 - x1, y0 - y1
     ff = d / (dx * dx + dy * dy) ** .5
@@ -4321,10 +4319,7 @@ def __init__(self, xyA, xyB, coordsA, coordsB=None,
         self._annotation_clip = None
 
     def _get_xy(self, x, y, s, axes=None):
-        """
-        calculate the pixel position of given point
-        """
-
+        """Calculate the pixel position of given point."""
         if axes is None:
             axes = self.axes
 
@@ -4418,7 +4413,7 @@ def _get_xy(self, x, y, s, axes=None):
                 y = b + y
             return x, y
         elif s == 'axes fraction':
-            #(0,0) is lower left, (1,1) is upper right of axes
+            # (0,0) is lower left, (1,1) is upper right of axes
             trans = axes.transAxes
             return trans.transform_point((x, y))
         elif isinstance(s, transforms.Transform):
@@ -4429,28 +4424,32 @@ def _get_xy(self, x, y, s, axes=None):
 
     def set_annotation_clip(self, b):
         """
-        set *annotation_clip* attribute.
+        Set the clipping behavior.
+
+        Parameters
+        ----------
+        b : bool or None
 
-          * True: the annotation will only be drawn when self.xy is inside the
-                   axes.
-          * False: the annotation will always be drawn regardless of its
-                    position.
-          * None: the self.xy will be checked only if *xycoords* is "data"
+            - *False*: The annotation will always be drawn regardless of its
+              position.
+            - *True*: The annotation will only be drawn if ``self.xy`` is
+              inside the axes.
+            - *None*: The annotation will only be drawn if ``self.xy`` is
+              inside the axes and  ``self.xycoords == "data"``.
         """
         self._annotation_clip = b
         self.stale = True
 
     def get_annotation_clip(self):
         """
-        Return *annotation_clip* attribute.
-        See :meth:`set_annotation_clip` for the meaning of return values.
+        Return the clipping behavior.
+
+        See `.set_annotation_clip` for the meaning of the return value.
         """
         return self._annotation_clip
 
     def get_path_in_displaycoord(self):
-        """
-        Return the mutated path of the arrow in the display coord
-        """
+        """Return the mutated path of the arrow in display coordinates."""
 
         dpi_cor = self.get_dpi_cor()
 
diff --git a/lib/matplotlib/patheffects.py b/lib/matplotlib/patheffects.py
index b39107753668..b1e99154535a 100644
--- a/lib/matplotlib/patheffects.py
+++ b/lib/matplotlib/patheffects.py
@@ -185,7 +185,7 @@ def __init__(self, offset=(0, 0), **kwargs):
 
     def draw_path(self, renderer, gc, tpath, affine, rgbFace):
         """
-        draw the path with updated gc.
+        Draw the path with updated gc.
         """
         # Do not modify the input! Use copy instead.
 
diff --git a/lib/matplotlib/projections/polar.py b/lib/matplotlib/projections/polar.py
index e653f43e8eba..ddc565208b57 100644
--- a/lib/matplotlib/projections/polar.py
+++ b/lib/matplotlib/projections/polar.py
@@ -236,6 +236,7 @@ def pan(self, numsteps):
         return self.base.pan(numsteps)
 
     def refresh(self):
+        # docstring inherited
         return self.base.refresh()
 
     def view_limits(self, vmin, vmax):
@@ -427,6 +428,7 @@ def zoom(self, direction):
         return self.base.zoom(direction)
 
     def refresh(self):
+        # docstring inherited
         return self.base.refresh()
 
     def view_limits(self, vmin, vmax):
diff --git a/lib/matplotlib/ticker.py b/lib/matplotlib/ticker.py
index 17bfefa0faae..5039b0230cf6 100644
--- a/lib/matplotlib/ticker.py
+++ b/lib/matplotlib/ticker.py
@@ -1187,7 +1187,7 @@ def __call__(self, x, pos=None):
         return s
 
     def format_data_short(self, value):
-        'return a short formatted string representation of a number'
+        """Return a short formatted string representation of a number."""
         return '%-12g' % value
 
 
@@ -1506,7 +1506,7 @@ def set_params(self, **kwargs):
             str(type(self)))
 
     def __call__(self):
-        """Return the locations of the ticks"""
+        """Return the locations of the ticks."""
         # note: some locators return data limits, other return view limits,
         # hence there is no *one* interface to call self.tick_values.
         raise NotImplementedError('Derived must override')
@@ -1532,7 +1532,7 @@ def view_limits(self, vmin, vmax):
         return mtransforms.nonsingular(vmin, vmax)
 
     def autoscale(self):
-        """autoscale the view limits"""
+        """Autoscale the view limits."""
         return self.view_limits(*self.axis.get_view_interval())
 
     def pan(self, numsteps):
@@ -1562,7 +1562,7 @@ def zoom(self, direction):
         self.axis.set_view_interval(vmin + step, vmax - step, ignore=True)
 
     def refresh(self):
-        """refresh internal information based on current lim"""
+        """Refresh internal information based on current limits."""
         pass
 
 
@@ -1574,7 +1574,7 @@ class IndexLocator(Locator):
     useful for x ticks.
     """
     def __init__(self, base, offset):
-        'place ticks on the i-th data points where (i-offset)%base==0'
+        """Place ticks every *base* data point, starting at *offset*."""
         self._base = base
         self.offset = offset
 
@@ -2063,7 +2063,7 @@ def view_limits(self, dmin, dmax):
 
 @cbook.deprecated("3.1")
 def decade_down(x, base=10):
-    'floor x to the nearest lower decade'
+    """Floor x to the nearest lower decade."""
     if x == 0.0:
         return -base
     lx = np.floor(np.log(x) / np.log(base))
@@ -2072,7 +2072,7 @@ def decade_down(x, base=10):
 
 @cbook.deprecated("3.1")
 def decade_up(x, base=10):
-    'ceil x to the nearest higher decade'
+    """Ceil x to the nearest higher decade."""
     if x == 0.0:
         return base
     lx = np.ceil(np.log(x) / np.log(base))
@@ -2191,14 +2191,12 @@ def set_params(self, base=None, subs=None, numdecs=None, numticks=None):
     # usual and desired API.
 
     def base(self, base):
-        """
-        set the base of the log scaling (major tick every base**i, i integer)
-        """
+        """Set the log base (major tick every ``base**i``, i integer)."""
         self._base = float(base)
 
     def subs(self, subs):
         """
-        set the minor ticks for the log scaling every base**i*subs[j]
+        Set the minor ticks for the log scaling every ``base**i*subs[j]``.
         """
         if subs is None:  # consistency with previous bad API
             self._subs = 'auto'
@@ -2350,9 +2348,7 @@ class SymmetricalLogLocator(Locator):
     """
 
     def __init__(self, transform=None, subs=None, linthresh=None, base=None):
-        """
-        place ticks on the location= base**i*subs[j]
-        """
+        """Place ticks on the locations ``base**i*subs[j]``."""
         if transform is not None:
             self._base = transform.base
             self._linthresh = transform.linthresh
@@ -2376,7 +2372,7 @@ def set_params(self, subs=None, numticks=None):
             self._subs = subs
 
     def __call__(self):
-        'Return the locations of the ticks'
+        """Return the locations of the ticks."""
         # Note, these are untransformed coordinates
         vmin, vmax = self.axis.get_view_interval()
         return self.tick_values(vmin, vmax)
@@ -2512,9 +2508,7 @@ class LogitLocator(Locator):
     """
 
     def __init__(self, minor=False):
-        """
-        place ticks on the logit locations
-        """
+        """Place ticks on the logit locations."""
         self.minor = minor
 
     def set_params(self, minor=None):
@@ -2523,7 +2517,7 @@ def set_params(self, minor=None):
             self.minor = minor
 
     def __call__(self):
-        'Return the locations of the ticks'
+        """Return the locations of the ticks."""
         vmin, vmax = self.axis.get_view_interval()
         return self.tick_values(vmin, vmax)
 
@@ -2698,7 +2692,7 @@ def tick_values(self, vmin, vmax):
                                   '%s type.' % type(self))
 
     def refresh(self):
-        'refresh internal information based on current lim'
+        # docstring inherited
         vmin, vmax = self.axis.get_view_interval()
         vmin, vmax = mtransforms.nonsingular(vmin, vmax, expander=0.05)
         d = abs(vmax - vmin)
@@ -2712,7 +2706,7 @@ def view_limits(self, vmin, vmax):
         return self._locator.view_limits(vmin, vmax)
 
     def get_locator(self, d):
-        'pick the best locator based on a distance'
+        """Pick the best locator based on a distance *d*."""
         d = abs(d)
         if d <= 0:
             locator = MultipleLocator(0.2)