Fix most instances of D404 ("docstring should not start with 'this').

... and associated rewordings.

lib/matplotlib/__init__.py

@@ -1,5 +1,5 @@
 """
-This is an object-oriented plotting library.
+An object-oriented plotting library.
 
 A procedural interface is provided by the companion pyplot module,
 which may be imported directly, e.g.::

lib/matplotlib/_constrained_layout.py

@@ -1,18 +1,16 @@
 """
-This module provides the routine to adjust subplot layouts so that there are
-no overlapping axes or axes decorations.  All axes decorations are dealt with
-(labels, ticks, titles, ticklabels) and some dependent artists are also dealt
-with (colorbar, suptitle, legend).
-
-Layout is done via :meth:`~matplotlib.gridspec`, with one constraint per
-gridspec, so it is possible to have overlapping axes if the gridspecs
-overlap (i.e. using :meth:`~matplotlib.gridspec.GridSpecFromSubplotSpec`).
-Axes placed using ``figure.subplots()`` or ``figure.add_subplots()`` will
-participate in the layout.  Axes manually placed via ``figure.add_axes()``
-will not.
+Adjust subplot layouts so that there are no overlapping axes or axes
+decorations.  All axes decorations are dealt with (labels, ticks, titles,
+ticklabels) and some dependent artists are also dealt with (colorbar, suptitle,
+legend).
 
-See Tutorial: :doc:`/tutorials/intermediate/constrainedlayout_guide`
+Layout is done via `~matplotlib.gridspec`, with one constraint per gridspec,
+so it is possible to have overlapping axes if the gridspecs overlap (i.e.
+using `~matplotlib.gridspec.GridSpecFromSubplotSpec`).  Axes placed using
+``figure.subplots()`` or ``figure.add_subplots()`` will participate in the
+layout.  Axes manually placed via ``figure.add_axes()`` will not.
 
+See Tutorial: :doc:`/tutorials/intermediate/constrainedlayout_guide`
 """
 
 # Development Notes:

lib/matplotlib/afm.py

@@ -1,14 +1,16 @@
 """
-This is a python interface to Adobe Font Metrics Files.  Although a
-number of other python implementations exist, and may be more complete
-than this, it was decided not to go with them because they were either:
+A python interface to Adobe Font Metrics Files.
+
+Although a number of other python implementations exist, and may be more
+complete than this, it was decided not to go with them because they were
+either:
 
 1) copyrighted or used a non-BSD compatible license
 2) had too many dependencies and a free standing lib was needed
 3) did more than needed and it was easier to write afresh rather than
    figure out how to get just what was needed.
 
-It is pretty easy to use, and requires only built-in python libs:
+It is pretty easy to use, and has no external depedencies:
 
 >>> import matplotlib as mpl
 >>> from pathlib import Path

lib/matplotlib/animation.py

@@ -890,12 +890,10 @@ def finish(self):
 
 class Animation:
     """
-    This class wraps the creation of an animation using matplotlib.
+    A base class for Animations.
 
-    It is only a base class which should be subclassed to provide
-    needed behavior.
-
-    This class is not typically used directly.
+    This class is not usable as is, and should be subclassed to provide needed
+    behavior.
 
     Parameters
     ----------

lib/matplotlib/axes/_base.py

@@ -2763,9 +2763,10 @@ def draw(self, renderer=None, inframe=False):
 
     def draw_artist(self, a):
         """
-        This method can only be used after an initial draw which
-        caches the renderer.  It is used to efficiently update Axes
-        data (axis ticks, labels, etc are not updated).
+        Efficiently redraw a single artist.
+
+        This method can only be used after an initial draw which caches the
+        renderer.
         """
         if self.figure._cachedRenderer is None:
             raise AttributeError("draw_artist can only be used after an "
@@ -2774,9 +2775,11 @@ def draw_artist(self, a):
 
     def redraw_in_frame(self):
         """
-        This method can only be used after an initial draw which
-        caches the renderer.  It is used to efficiently update Axes
-        data (axis ticks, labels, etc are not updated).
+        It is used to efficiently redraw Axes data (axis ticks, labels, etc.,
+        are not redrawn).
+
+        This method can only be used after an initial draw which caches the
+        renderer.
         """
         if self.figure._cachedRenderer is None:
             raise AttributeError("redraw_in_frame can only be used after an "

lib/matplotlib/axes/_subplots.py

@@ -179,7 +179,7 @@ def _make_twin_axes(self, *args, **kwargs):
 @functools.lru_cache(None)
 def subplot_class_factory(axes_class=None):
     """
-    This makes a new class that inherits from `.SubplotBase` and the
+    Make a new class that inherits from `.SubplotBase` and the
     given axes_class (which is assumed to be a subclass of `.axes.Axes`).
     This is perhaps a little bit roundabout to make a new class on
     the fly like this, but it means that a new Subplot class does
@@ -207,8 +207,9 @@ def subplot_class_factory(axes_class=None):
 
 def _picklable_subplot_class_constructor(axes_class):
     """
-    This stub class exists to return the appropriate subplot class when called
-    with an axes class. This is purely to allow pickling of Axes and Subplots.
+    Stub factory that returns an empty instance of the appropriate subplot
+    class when called with an axes class. This is purely to allow pickling of
+    Axes and Subplots.
     """
     subplot_class = subplot_class_factory(axes_class)
     return subplot_class.__new__(subplot_class)

lib/matplotlib/backend_bases.py

@@ -237,9 +237,8 @@ def draw_quad_mesh(self, gc, master_transform, meshWidth, meshHeight,
                        coordinates, offsets, offsetTrans, facecolors,
                        antialiased, edgecolors):
         """
-        This provides a fallback implementation of
-        :meth:`draw_quad_mesh` that generates paths and then calls
-        :meth:`draw_path_collection`.
+        Fallback implementation of :meth:`draw_quad_mesh` that generates paths
+        and then calls :meth:`draw_path_collection`.
         """
 
         from matplotlib.collections import QuadMesh
@@ -298,9 +297,8 @@ def draw_gouraud_triangles(self, gc, triangles_array, colors_array,
     def _iter_collection_raw_paths(self, master_transform, paths,
                                    all_transforms):
         """
-        This is a helper method (along with :meth:`_iter_collection`) to make
-        it easier to write a space-efficient :meth:`draw_path_collection`
-        implementation in a backend.
+        Helper method (along with :meth:`_iter_collection`) to implement
+        :meth:`draw_path_collection` in a space-efficient manner.
 
         This method yields all of the base path/transform
         combinations, given a master transform, a list of paths and
@@ -348,10 +346,8 @@ def _iter_collection(self, gc, master_transform, all_transforms,
                          edgecolors, linewidths, linestyles,
                          antialiaseds, urls, offset_position):
         """
-        This is a helper method (along with
-        :meth:`_iter_collection_raw_paths`) to make it easier to write
-        a space-efficient :meth:`draw_path_collection` implementation in a
-        backend.
+        Helper method (along with :meth:`_iter_collection_raw_paths`) to
+        implement :meth:`draw_path_collection` in a space-efficient manner.
 
         This method yields all of the path, offset and graphics
         context combinations to draw the path collection.  The caller

lib/matplotlib/backends/backend_template.py

@@ -1,5 +1,5 @@
 """
-This is a fully functional do nothing backend to provide a template to backend
+A fully functional, do-nothing backend intended as a template for backend
 writers.  It is fully functional in that you can select it as a backend e.g.
 with ::
 

lib/matplotlib/backends/backend_wx.py

@@ -1026,9 +1026,9 @@ def Destroy(self, *args, **kwargs):
 
 class FigureManagerWx(FigureManagerBase):
     """
-    This class contains the FigureCanvas and GUI frame
+    A class contains the FigureCanvas and GUI frame.
 
-    It is instantiated by GcfWx whenever a new figure is created. GcfWx is
+    It is instantiated by Gcf whenever a new figure is created.  Gcf is
     responsible for managing multiple instances of FigureManagerWx.
 
     Attributes

lib/matplotlib/backends/qt_editor/figureoptions.py

@@ -170,7 +170,7 @@ def prepare_data(d, init):
         datalist.append((mappables, "Images, etc.", ""))
 
     def apply_callback(data):
-        """This function will be called to apply changes"""
+        """A callback to apply changes."""
         orig_xlim = axes.get_xlim()
         orig_ylim = axes.get_ylim()
 

lib/matplotlib/blocking_input.py

@@ -1,6 +1,5 @@
 """
-This provides several classes used for blocking interaction with figure
-windows:
+Classes used for blocking interaction with figure windows:
 
 `BlockingInput`
     Creates a callable object to retrieve events in a blocking way for

lib/matplotlib/cbook/__init__.py

@@ -758,40 +758,38 @@ def recurse(obj, start, all, current_path):
 
 class Grouper:
     """
-    This class provides a lightweight way to group arbitrary objects
-    together into disjoint sets when a full-blown graph data structure
-    would be overkill.
+    A disjoint-set data structure.
 
     Objects can be joined using :meth:`join`, tested for connectedness
     using :meth:`joined`, and all disjoint sets can be retrieved by
     using the object as an iterator.
 
     The objects being joined must be hashable and weak-referenceable.
 
-    For example:
-
-        >>> from matplotlib.cbook import Grouper
-        >>> class Foo:
-        ...     def __init__(self, s):
-        ...         self.s = s
-        ...     def __repr__(self):
-        ...         return self.s
-        ...
-        >>> a, b, c, d, e, f = [Foo(x) for x in 'abcdef']
-        >>> grp = Grouper()
-        >>> grp.join(a, b)
-        >>> grp.join(b, c)
-        >>> grp.join(d, e)
-        >>> sorted(map(tuple, grp))
-        [(a, b, c), (d, e)]
-        >>> grp.joined(a, b)
-        True
-        >>> grp.joined(a, c)
-        True
-        >>> grp.joined(a, d)
-        False
-
+    Examples
+    --------
+    >>> from matplotlib.cbook import Grouper
+    >>> class Foo:
+    ...     def __init__(self, s):
+    ...         self.s = s
+    ...     def __repr__(self):
+    ...         return self.s
+    ...
+    >>> a, b, c, d, e, f = [Foo(x) for x in 'abcdef']
+    >>> grp = Grouper()
+    >>> grp.join(a, b)
+    >>> grp.join(b, c)
+    >>> grp.join(d, e)
+    >>> sorted(map(tuple, grp))
+    [(a, b, c), (d, e)]
+    >>> grp.joined(a, b)
+    True
+    >>> grp.joined(a, c)
+    True
+    >>> grp.joined(a, d)
+    False
     """
+
     def __init__(self, init=()):
         self._mapping = {weakref.ref(x): [weakref.ref(x)] for x in init}
 

lib/matplotlib/cm.py

@@ -150,11 +150,12 @@ def get_cmap(name=None, lut=None):
 
 class ScalarMappable:
     """
-    This is a mixin class to support scalar data to RGBA mapping.
-    The ScalarMappable makes use of data normalization before returning
-    RGBA colors from the given colormap.
+    A mixin class to map scalar data to RGBA.
 
+    The ScalarMappable applies data normalization before returning RGBA colors
+    from the given colormap.
     """
+
     def __init__(self, norm=None, cmap=None):
         """
 

lib/matplotlib/collections.py

@@ -1118,7 +1118,7 @@ def set_verts(self, verts, closed=True):
     set_paths = set_verts
 
     def set_verts_and_codes(self, verts, codes):
-        """This allows one to initialize vertices with path codes."""
+        """Initialize vertices with path codes."""
         if len(verts) != len(codes):
             raise ValueError("'codes' must be a 1D list or array "
                              "with the same length of 'verts'")

lib/matplotlib/colorbar.py

@@ -297,8 +297,6 @@ class _ColorbarLogLocator(ticker.LogLocator):
     """
     def __init__(self, colorbar, *args, **kwargs):
         """
-        _ColorbarLogLocator(colorbar, *args, **kwargs)
-
         This ticker needs to know the *colorbar* so that it can access
         its *vmin* and *vmax*.  Otherwise it is the same as
         `~.ticker.LogLocator`.  The ``*args`` and ``**kwargs`` are the

lib/matplotlib/colors.py

@@ -361,7 +361,7 @@ def to_hex(c, keep_alpha=False):
 
 class ColorConverter:
     """
-    This class is only kept for backwards compatibility.
+    A class only kept for backwards compatibility.
 
     Its functionality is entirely provided by module-level functions.
     """

lib/matplotlib/contour.py

@@ -1,5 +1,5 @@
 """
-These are classes to support contour plotting and labelling for the Axes class.
+Classes to support contour plotting and labelling for the Axes class.
 """
 
 from numbers import Integral
@@ -313,21 +313,22 @@ def locate_label(self, linecontour, labelwidth):
 
     def calc_label_rot_and_inline(self, slc, ind, lw, lc=None, spacing=5):
         """
-        This function calculates the appropriate label rotation given
-        the linecontour coordinates in screen units, the index of the
-        label location and the label width.
+        Calculate the appropriate label rotation given the linecontour
+        coordinates in screen units, the index of the label location and the
+        label width.
 
-        It will also break contour and calculate inlining if *lc* is
-        not empty (lc defaults to the empty list if None).  *spacing*
-        is the space around the label in pixels to leave empty.
+        If *lc* is not None or empty, also break contours and compute
+        inlining.
 
-        Do both of these tasks at once to avoid calculating path lengths
+        *spacing* is the empty space to leave around the label, in pixels.
+
+        Both tasks are done together to avoid calculating path lengths
         multiple times, which is relatively costly.
 
-        The method used here involves calculating the path length
-        along the contour in pixel coordinates and then looking
-        approximately label width / 2 away from central point to
-        determine rotation and then to break contour if desired.
+        The method used here involves computing the path length along the
+        contour in pixel coordinates and then looking approximately (label
+        width / 2) away from central point to determine rotation and then to
+        break contour if desired.
         """
 
         if lc is None:

lib/matplotlib/dates.py

@@ -563,7 +563,7 @@ def __call__(self, x, pos=0):
 
 class ConciseDateFormatter(ticker.Formatter):
     """
-    This class attempts to figure out the best format to use for the
+    A `.Formatter` which attempts to figure out the best format to use for the
     date, and to make it as compact as possible, but still be complete. This is
     most useful when used with the `AutoDateLocator`::
 
@@ -761,8 +761,8 @@ def format_data_short(self, value):
 
 class AutoDateFormatter(ticker.Formatter):
     """
-    This class attempts to figure out the best format to use.  This is
-    most useful when used with the `AutoDateLocator`.
+    A `.Formatter` which attempts to figure out the best format to use.  This
+    is most useful when used with the `AutoDateLocator`.
 
     The AutoDateFormatter has a scale dictionary that maps the scale
     of the tick (the distance in days between one major tick) and a

lib/matplotlib/legend_handler.py

@@ -1,5 +1,5 @@
 """
-This module defines default legend handlers.
+Default legend handlers.
 
 It is strongly encouraged to have read the :doc:`legend guide
 </tutorials/intermediate/legend_guide>` before this documentation.
@@ -21,7 +21,6 @@
 derived from the base class (HandlerBase) with the following method::
 
     def legend_artist(self, legend, orig_handle, fontsize, handlebox)
-
 """
 
 from itertools import cycle

lib/matplotlib/lines.py

@@ -1,6 +1,6 @@
 """
-This module contains all the 2D line class which can draw with a
-variety of line styles, markers and colors.
+The 2D line class which can draw with a variety of line styles, markers and
+colors.
 """
 
 # TODO: expose cap and join style attrs

lib/matplotlib/markers.py

@@ -1,7 +1,6 @@
 r"""
-This module contains functions to handle markers.  Used by both the
-marker functionality of `~matplotlib.axes.Axes.plot` and
-`~matplotlib.axes.Axes.scatter`.
+Functions to handle markers; used by the marker functionality of
+`~matplotlib.axes.Axes.plot` and `~matplotlib.axes.Axes.scatter`.
 
 All possible markers are defined here: