From 9b6abd0b4933811e0a45c2535ab8fd107db65dd9 Mon Sep 17 00:00:00 2001
From: Oscar Gustafsson <oscar.gustafsson@gmail.com>
Date: Sun, 20 Nov 2022 14:16:00 +0100
Subject: [PATCH] DOC: improve grammar and consistency

---
 lib/matplotlib/artist.py        | 16 ++++++-------
 lib/matplotlib/axis.py          | 16 ++++++-------
 lib/matplotlib/bezier.py        | 40 ++++++++++++++++-----------------
 lib/matplotlib/collections.py   |  4 ++--
 lib/matplotlib/colorbar.py      |  4 ++--
 lib/matplotlib/colors.py        | 22 +++++++++---------
 lib/matplotlib/contour.py       | 14 ++++++------
 lib/matplotlib/dates.py         | 27 +++++++++++-----------
 lib/matplotlib/dviread.py       |  4 ++--
 lib/matplotlib/figure.py        | 35 +++++++++++++++--------------
 lib/matplotlib/font_manager.py  | 16 ++++++-------
 lib/matplotlib/gridspec.py      | 12 +++++-----
 lib/matplotlib/image.py         |  2 +-
 lib/matplotlib/layout_engine.py |  4 ++--
 14 files changed, 109 insertions(+), 107 deletions(-)

diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py
index 1ca1c1d3e37e..99577ece532d 100644
--- a/lib/matplotlib/artist.py
+++ b/lib/matplotlib/artist.py
@@ -204,7 +204,7 @@ def remove(self):
         Note: there is no support for removing the artist's legend entry.
         """
 
-        # There is no method to set the callback.  Instead the parent should
+        # There is no method to set the callback.  Instead, the parent should
         # set the _remove_method attribute directly.  This would be a
         # protected attribute if Python supported that sort of thing.  The
         # callback has one parameter, which is the child to be removed.
@@ -521,7 +521,7 @@ def pick(self, mouseevent):
                 # tick label) can be outside the bounding box of the
                 # Axes and inaxes will be None
                 # also check that ax is None so that it traverse objects
-                # which do no have an axes property but children might
+                # which do not have an axes property but children might
                 a.pick(mouseevent)
 
     def set_picker(self, picker):
@@ -878,7 +878,7 @@ def set_clip_on(self, b):
         """
         Set whether the artist uses clipping.
 
-        When False artists will be visible outside of the Axes which
+        When False, artists will be visible outside the Axes which
         can lead to unexpected results.
 
         Parameters
@@ -1145,7 +1145,7 @@ def _update_props(self, props, errfmt):
         Helper for `.Artist.set` and `.Artist.update`.
 
         *errfmt* is used to generate error messages for invalid property
-        names; it get formatted with ``type(self)`` and the property name.
+        names; it gets formatted with ``type(self)`` and the property name.
         """
         ret = []
         with cbook._setattr_cm(self, eventson=False):
@@ -1371,7 +1371,7 @@ def set_mouseover(self, mouseover):
 def _get_tightbbox_for_layout_only(obj, *args, **kwargs):
     """
     Matplotlib's `.Axes.get_tightbbox` and `.Axis.get_tightbbox` support a
-    *for_layout_only* kwarg; this helper tries to uses the kwarg but skips it
+    *for_layout_only* kwarg; this helper tries to use the kwarg but skips it
     when encountering third-party subclasses that do not support it.
     """
     try:
@@ -1463,7 +1463,7 @@ def get_valid_values(self, attr):
         # although barely relevant wrt. matplotlib's total import time.
         param_name = func.__code__.co_varnames[1]
         # 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.
+        # varargs (it can't be a varkwargs) but it's not really worth it.
         match = re.search(r"(?m)^ *\*?{} : (.+)".format(param_name), docstring)
         if match:
             return match.group(1)
@@ -1523,7 +1523,7 @@ def aliased_name(self, s):
         """
         Return 'PROPNAME or alias' if *s* has an alias, else return 'PROPNAME'.
 
-        e.g., for the line markerfacecolor property, which has an
+        For example, for the line markerfacecolor property, which has an
         alias, return 'markerfacecolor or mfc' and for the transform
         property, which does not, return 'transform'.
         """
@@ -1551,7 +1551,7 @@ def aliased_name_rest(self, s, target):
         Return 'PROPNAME or alias' if *s* has an alias, else return 'PROPNAME',
         formatted for reST.
 
-        e.g., for the line markerfacecolor property, which has an
+        For example, for the line markerfacecolor property, which has an
         alias, return 'markerfacecolor or mfc' and for the transform
         property, which does not, return 'transform'.
         """
diff --git a/lib/matplotlib/axis.py b/lib/matplotlib/axis.py
index 09b541b4b1f8..a16a7851f455 100644
--- a/lib/matplotlib/axis.py
+++ b/lib/matplotlib/axis.py
@@ -1,5 +1,5 @@
 """
-Classes for the ticks and x and y axis.
+Classes for the ticks and x- and y-axis.
 """
 
 import datetime
@@ -278,13 +278,13 @@ def _get_text2(self):
         """Get the default Text 2 instance."""
 
     def _get_tick1line(self):
-        """Get the default line2D instance for tick1."""
+        """Get the default `.Line2D` instance for tick1."""
 
     def _get_tick2line(self):
-        """Get the default line2D instance for tick2."""
+        """Get the default `.Line2D` instance for tick2."""
 
     def _get_gridline(self):
-        """Get the default grid Line2d instance for this tick."""
+        """Get the default grid `.Line2D` instance for this tick."""
 
     def get_loc(self):
         """Return the tick location (data coords) as a scalar."""
@@ -796,7 +796,7 @@ def _set_axes_scale(self, value, **kwargs):
 
         Notes
         -----
-        By default, Matplotlib supports the above mentioned scales.
+        By default, Matplotlib supports the above-mentioned scales.
         Additionally, custom scales may be registered using
         `matplotlib.scale.register_scale`. These scales can then also
         be used here.
@@ -1591,7 +1591,7 @@ def grid(self, visible=None, which='major', **kwargs):
     def update_units(self, data):
         """
         Introspect *data* for units converter and update the
-        axis.converter instance if necessary. Return *True*
+        ``axis.converter`` instance if necessary. Return *True*
         if *data* is registered for unit conversion.
         """
         converter = munits.registry.get_converter(data)
@@ -2034,7 +2034,7 @@ def _get_tick_boxes_siblings(self, renderer):
         Get the bounding boxes for this `.axis` and its siblings
         as set by `.Figure.align_xlabels` or  `.Figure.align_ylabels`.
 
-        By default it just gets bboxes for self.
+        By default, it just gets bboxes for *self*.
         """
         # Get the Grouper keeping track of x or y label groups for this figure.
         axis_names = [
@@ -2213,7 +2213,7 @@ def _init(self):
         self.offset_text_position = 'bottom'
 
     def contains(self, mouseevent):
-        """Test whether the mouse event occurred in the x axis."""
+        """Test whether the mouse event occurred in the x-axis."""
         inside, info = self._default_contains(mouseevent)
         if inside is not None:
             return inside, info
diff --git a/lib/matplotlib/bezier.py b/lib/matplotlib/bezier.py
index 1c92487b9b9f..f310f287e2c0 100644
--- a/lib/matplotlib/bezier.py
+++ b/lib/matplotlib/bezier.py
@@ -1,5 +1,5 @@
 """
-A module providing some utility functions regarding Bezier path manipulation.
+A module providing some utility functions regarding Bézier path manipulation.
 """
 
 from functools import lru_cache
@@ -94,7 +94,7 @@ def _de_casteljau1(beta, t):
 
 def split_de_casteljau(beta, t):
     """
-    Split a Bezier segment defined by its control points *beta* into two
+    Split a Bézier segment defined by its control points *beta* into two
     separate segments divided at *t* and return their control points.
     """
     beta = np.asarray(beta)
@@ -113,7 +113,7 @@ def split_de_casteljau(beta, t):
 def find_bezier_t_intersecting_with_closedpath(
         bezier_point_at_t, inside_closedpath, t0=0., t1=1., tolerance=0.01):
     """
-    Find the intersection of the Bezier curve with a closed path.
+    Find the intersection of the Bézier curve with a closed path.
 
     The intersection point *t* is approximated by two parameters *t0*, *t1*
     such that *t0* <= *t* <= *t1*.
@@ -126,7 +126,7 @@ def find_bezier_t_intersecting_with_closedpath(
     Parameters
     ----------
     bezier_point_at_t : callable
-        A function returning x, y coordinates of the Bezier at parameter *t*.
+        A function returning x, y coordinates of the Bézier at parameter *t*.
         It must have the signature::
 
             bezier_point_at_t(t: float) -> tuple[float, float]
@@ -146,7 +146,7 @@ def find_bezier_t_intersecting_with_closedpath(
     Returns
     -------
     t0, t1 : float
-        The Bezier path parameters.
+        The Bézier path parameters.
     """
     start = bezier_point_at_t(t0)
     end = bezier_point_at_t(t1)
@@ -180,7 +180,7 @@ def find_bezier_t_intersecting_with_closedpath(
 
 class BezierSegment:
     """
-    A d-dimensional Bezier segment.
+    A d-dimensional Bézier segment.
 
     Parameters
     ----------
@@ -199,7 +199,7 @@ def __init__(self, control_points):
 
     def __call__(self, t):
         """
-        Evaluate the Bezier curve at point(s) t in [0, 1].
+        Evaluate the Bézier curve at point(s) *t* in [0, 1].
 
         Parameters
         ----------
@@ -239,7 +239,7 @@ def degree(self):
     @property
     def polynomial_coefficients(self):
         r"""
-        The polynomial coefficients of the Bezier curve.
+        The polynomial coefficients of the Bézier curve.
 
         .. warning:: Follows opposite convention from `numpy.polyval`.
 
@@ -247,7 +247,7 @@ def polynomial_coefficients(self):
         -------
         (n+1, d) array
             Coefficients after expanding in polynomial basis, where :math:`n`
-            is the degree of the bezier curve and :math:`d` its dimension.
+            is the degree of the Bézier curve and :math:`d` its dimension.
             These are the numbers (:math:`C_j`) such that the curve can be
             written :math:`\sum_{j=0}^n C_j t^j`.
 
@@ -308,12 +308,12 @@ def axis_aligned_extrema(self):
 def split_bezier_intersecting_with_closedpath(
         bezier, inside_closedpath, tolerance=0.01):
     """
-    Split a Bezier curve into two at the intersection with a closed path.
+    Split a Bézier curve into two at the intersection with a closed path.
 
     Parameters
     ----------
     bezier : (N, 2) array-like
-        Control points of the Bezier segment. See `.BezierSegment`.
+        Control points of the Bézier segment. See `.BezierSegment`.
     inside_closedpath : callable
         A function returning True if a given point (x, y) is inside the
         closed path. See also `.find_bezier_t_intersecting_with_closedpath`.
@@ -324,7 +324,7 @@ def split_bezier_intersecting_with_closedpath(
     Returns
     -------
     left, right
-        Lists of control points for the two Bezier segments.
+        Lists of control points for the two Bézier segments.
     """
 
     bz = BezierSegment(bezier)
@@ -461,13 +461,13 @@ def check_if_parallel(dx1, dy1, dx2, dy2, tolerance=1.e-5):
 
 def get_parallels(bezier2, width):
     """
-    Given the quadratic Bezier control points *bezier2*, returns
-    control points of quadratic Bezier lines roughly parallel to given
+    Given the quadratic Bézier control points *bezier2*, returns
+    control points of quadratic Bézier lines roughly parallel to given
     one separated by *width*.
     """
 
     # The parallel Bezier lines are constructed by following ways.
-    #  c1 and c2 are control points representing the begin and end of the
+    #  c1 and c2 are control points representing the start and end of the
     #  Bezier line.
     #  cm is the middle point
 
@@ -485,7 +485,7 @@ def get_parallels(bezier2, width):
         cos_t2, sin_t2 = cos_t1, sin_t1
     else:
         # t1 and t2 is the angle between c1 and cm, cm, c2.  They are
-        # also a angle of the tangential line of the path at c1 and c2
+        # also an angle of the tangential line of the path at c1 and c2
         cos_t1, sin_t1 = get_cos_sin(c1x, c1y, cmx, cmy)
         cos_t2, sin_t2 = get_cos_sin(cmx, cmy, c2x, c2y)
 
@@ -535,7 +535,7 @@ def get_parallels(bezier2, width):
 
 def find_control_points(c1x, c1y, mmx, mmy, c2x, c2y):
     """
-    Find control points of the Bezier curve passing through (*c1x*, *c1y*),
+    Find control points of the Bézier curve passing through (*c1x*, *c1y*),
     (*mmx*, *mmy*), and (*c2x*, *c2y*), at parametric values 0, 0.5, and 1.
     """
     cmx = .5 * (4 * mmx - (c1x + c2x))
@@ -545,8 +545,8 @@ def find_control_points(c1x, c1y, mmx, mmy, c2x, c2y):
 
 def make_wedged_bezier2(bezier2, width, w1=1., wm=0.5, w2=0.):
     """
-    Being similar to get_parallels, returns control points of two quadratic
-    Bezier lines having a width roughly parallel to given one separated by
+    Being similar to `get_parallels`, returns control points of two quadratic
+    Bézier lines having a width roughly parallel to given one separated by
     *width*.
     """
 
@@ -556,7 +556,7 @@ def make_wedged_bezier2(bezier2, width, w1=1., wm=0.5, w2=0.):
     c3x, c3y = bezier2[2]
 
     # t1 and t2 is the angle between c1 and cm, cm, c3.
-    # They are also a angle of the tangential line of the path at c1 and c3
+    # They are also an angle of the tangential line of the path at c1 and c3
     cos_t1, sin_t1 = get_cos_sin(c1x, c1y, cmx, cmy)
     cos_t2, sin_t2 = get_cos_sin(cmx, cmy, c3x, c3y)
 
diff --git a/lib/matplotlib/collections.py b/lib/matplotlib/collections.py
index 8f13cfc379e9..e57ac69bed51 100644
--- a/lib/matplotlib/collections.py
+++ b/lib/matplotlib/collections.py
@@ -715,7 +715,7 @@ def set_color(self, c):
 
         Parameters
         ----------
-        c : color or list of rgba tuples
+        c : color or list of RGBA tuples
 
         See Also
         --------
@@ -1468,7 +1468,7 @@ def set_color(self, c):
         ----------
         c : color or list of colors
             Single color (all lines have same color), or a
-            sequence of rgba tuples; if it is a sequence the lines will
+            sequence of RGBA tuples; if it is a sequence the lines will
             cycle through the sequence.
         """
         self.set_edgecolor(c)
diff --git a/lib/matplotlib/colorbar.py b/lib/matplotlib/colorbar.py
index 402ba4085e50..a733a1224a25 100644
--- a/lib/matplotlib/colorbar.py
+++ b/lib/matplotlib/colorbar.py
@@ -821,7 +821,7 @@ def add_lines(self, *args, **kwargs):
 
     def update_ticks(self):
         """
-        Setup the ticks and ticklabels. This should not be needed by users.
+        Set up the ticks and ticklabels. This should not be needed by users.
         """
         # Get the locator and formatter; defaults to self._locator if not None.
         self._get_ticker_locator_formatter()
@@ -1024,7 +1024,7 @@ def _set_scale(self, scale, **kwargs):
 
         Notes
         -----
-        By default, Matplotlib supports the above mentioned scales.
+        By default, Matplotlib supports the above-mentioned scales.
         Additionally, custom scales may be registered using
         `matplotlib.scale.register_scale`. These scales can then also
         be used here.
diff --git a/lib/matplotlib/colors.py b/lib/matplotlib/colors.py
index 0313565a2583..34be1553c949 100644
--- a/lib/matplotlib/colors.py
+++ b/lib/matplotlib/colors.py
@@ -663,7 +663,7 @@ def __init__(self, name, N=256):
         name : str
             The name of the colormap.
         N : int
-            The number of rgb quantization levels.
+            The number of RGB quantization levels.
         """
         self.name = name
         self.N = int(N)  # ensure that N is always int
@@ -1039,7 +1039,7 @@ def from_list(name, colors, N=256, gamma=1.0):
             If (value, color) pairs are given, the mapping is from *value*
             to *color*. This can be used to divide the range unevenly.
         N : int
-            The number of rgb quantization levels.
+            The number of RGB quantization levels.
         gamma : float
         """
         if not np.iterable(colors):
@@ -1120,7 +1120,7 @@ class ListedColormap(Colormap):
     ----------
     colors : list, array
         List of Matplotlib color specifications, or an equivalent Nx3 or Nx4
-        floating point array (*N* rgb or rgba values).
+        floating point array (*N* RGB or RGBA values).
     name : str, optional
         String to identify the colormap.
     N : int, optional
@@ -2043,7 +2043,7 @@ def inverse(self, value):
 
 def rgb_to_hsv(arr):
     """
-    Convert float rgb values (in the range [0, 1]), in a numpy array to hsv
+    Convert float RGB values (in the range [0, 1]), in a numpy array to HSV
     values.
 
     Parameters
@@ -2054,7 +2054,7 @@ def rgb_to_hsv(arr):
     Returns
     -------
     (..., 3) ndarray
-       Colors converted to hsv values in range [0, 1]
+       Colors converted to HSV values in range [0, 1]
     """
     arr = np.asarray(arr)
 
@@ -2095,7 +2095,7 @@ def rgb_to_hsv(arr):
 
 def hsv_to_rgb(hsv):
     """
-    Convert hsv values to rgb.
+    Convert HSV values to RGB.
 
     Parameters
     ----------
@@ -2191,8 +2191,8 @@ class LightSource:
     Angles are in degrees, with the azimuth measured
     clockwise from north and elevation up from the zero plane of the surface.
 
-    `shade` is used to produce "shaded" rgb values for a data array.
-    `shade_rgb` can be used to combine an rgb image with an elevation map.
+    `shade` is used to produce "shaded" RGB values for a data array.
+    `shade_rgb` can be used to combine an RGB image with an elevation map.
     `hillshade` produces an illumination map of a surface.
     """
 
@@ -2496,7 +2496,7 @@ def blend_hsv(self, rgb, intensity, hsv_max_sat=None, hsv_max_val=None,
         which can then be used to plot the shaded image with imshow.
 
         The color of the resulting image will be darkened by moving the (s, v)
-        values (in hsv colorspace) toward (hsv_min_sat, hsv_min_val) in the
+        values (in HSV colorspace) toward (hsv_min_sat, hsv_min_val) in the
         shaded regions, or lightened by sliding (s, v) toward (hsv_max_sat,
         hsv_max_val) in regions that are illuminated.  The default extremes are
         chose so that completely shaded points are nearly black (s = 1, v = 0)
@@ -2561,7 +2561,7 @@ def blend_hsv(self, rgb, intensity, hsv_max_sat=None, hsv_max_val=None,
 
     def blend_soft_light(self, rgb, intensity):
         """
-        Combine an rgb image with an intensity map using "soft light" blending,
+        Combine an RGB image with an intensity map using "soft light" blending,
         using the "pegtop" formula.
 
         Parameters
@@ -2580,7 +2580,7 @@ def blend_soft_light(self, rgb, intensity):
 
     def blend_overlay(self, rgb, intensity):
         """
-        Combine an rgb image with an intensity map using "overlay" blending.
+        Combine an RGB image with an intensity map using "overlay" blending.
 
         Parameters
         ----------
diff --git a/lib/matplotlib/contour.py b/lib/matplotlib/contour.py
index 6015530bb5b3..f72a6dd9c83f 100644
--- a/lib/matplotlib/contour.py
+++ b/lib/matplotlib/contour.py
@@ -587,7 +587,7 @@ def _find_closest_point_on_path(xys, p):
         Projection of *p* onto *xys*.
     imin : (int, int)
         Consecutive indices of vertices of segment in *xys* where *proj* is.
-        Segments are considered as including their end-points; i.e if the
+        Segments are considered as including their end-points; i.e. if the
         closest point on the path is a node in *xys* with index *i*, this
         returns ``(i-1, i)``.  For the special case where *xys* is a single
         point, this returns ``(0, 0)``.
@@ -1032,13 +1032,13 @@ def _get_lowers_and_uppers(self):
     def _make_paths(self, segs, kinds):
         """
         Create and return Path objects for the specified segments and optional
-        kind codes.  segs is a list of numpy arrays, each array is either a
+        kind codes.  *segs* is a list of numpy arrays, each array is either a
         closed line loop or open line strip of 2D points with a shape of
-        (npoints, 2).  kinds is either None or a list (with the same length as
-        segs) of numpy arrays, each array is of shape (npoints,) and contains
-        the kinds codes for the corresponding line in segs.  If kinds is None
-        then the Path constructor creates the kind codes assuming that the line
-        is an open strip.
+        (npoints, 2).  *kinds* is either None or a list (with the same length
+        as *segs*) of numpy arrays, each array is of shape (npoints,) and
+        contains the kind codes for the corresponding line in *segs*.  If
+        *kinds* is None then the Path constructor creates the kind codes
+        assuming that the line is an open strip.
         """
         if kinds is None:
             return [mpath.Path(seg) for seg in segs]
diff --git a/lib/matplotlib/dates.py b/lib/matplotlib/dates.py
index d84d30455e18..bb7c9ae7fb3f 100644
--- a/lib/matplotlib/dates.py
+++ b/lib/matplotlib/dates.py
@@ -107,15 +107,15 @@
     # import constants for the days of the week
     from matplotlib.dates import MO, TU, WE, TH, FR, SA, SU
 
-    # tick on mondays every week
+    # tick on Mondays every week
     loc = WeekdayLocator(byweekday=MO, tz=tz)
 
-    # tick on mondays and saturdays
+    # tick on Mondays and Saturdays
     loc = WeekdayLocator(byweekday=(MO, SA))
 
 In addition, most of the constructors take an interval argument::
 
-    # tick on mondays every second week
+    # tick on Mondays every second week
     loc = WeekdayLocator(byweekday=MO, interval=2)
 
 The rrule locator allows completely general date ticking::
@@ -150,9 +150,9 @@
 * `AutoDateLocator`: On autoscale, this class picks the best `DateLocator`
   (e.g., `RRuleLocator`) to set the view limits and the tick locations.  If
   called with ``interval_multiples=True`` it will make ticks line up with
-  sensible multiples of the tick intervals.  E.g. if the interval is 4 hours,
-  it will pick hours 0, 4, 8, etc as ticks.  This behaviour is not guaranteed
-  by default.
+  sensible multiples of the tick intervals.  For example, if the interval is
+  4 hours, it will pick hours 0, 4, 8, etc. as ticks.  This behaviour is not
+  guaranteed by default.
 
 Date formatters
 ---------------
@@ -216,8 +216,8 @@ class __getattr__:
 
 def _get_tzinfo(tz=None):
     """
-    Generate tzinfo from a string or return tzinfo. If None,
-    retrieve the preferred timezone from the rcParams dictionary.
+    Generate `~datetime.tzinfo` from a string or return `~datetime.tzinfo`.
+    If None, retrieve the preferred timezone from the rcParams dictionary.
     """
     if tz is None:
         tz = mpl.rcParams['timezone']
@@ -1430,7 +1430,7 @@ def get_locator(self, dmin, dmax):
 
         # Loop over all the frequencies and try to find one that gives at
         # least a minticks tick positions.  Once this is found, look for
-        # an interval from an list specific to that frequency that gives no
+        # an interval from a list specific to that frequency that gives no
         # more than maxticks tick positions. Also, set up some ranges
         # (bymonth, etc.) as appropriate to be passed to rrulewrapper.
         for i, (freq, num) in enumerate(zip(self._freqs, nums)):
@@ -1664,7 +1664,7 @@ def __init__(self, byminute=None, interval=1, tz=None):
         Parameters
         ----------
         byminute : int or list of int, default: all minutes
-            Ticks will be placed on every minutes in *byminutes*. Default is
+            Ticks will be placed on every minute in *byminute*. Default is
             ``byminute=range(60)``, i.e., every minute.
         interval : int, default: 1
             The interval between each iteration. For example, if
@@ -1824,7 +1824,7 @@ class DateConverter(units.ConversionInterface):
     Converter for `datetime.date` and `datetime.datetime` data, or for
     date/time data represented as it would be converted by `date2num`.
 
-    The 'unit' tag for such data is None or a tzinfo instance.
+    The 'unit' tag for such data is None or a `~datetime.tzinfo` instance.
     """
 
     def __init__(self, *, interval_multiples=True):
@@ -1835,7 +1835,7 @@ def axisinfo(self, unit, axis):
         """
         Return the `~matplotlib.units.AxisInfo` for *unit*.
 
-        *unit* is a tzinfo instance or None.
+        *unit* is a `~datetime.tzinfo` instance or None.
         The *axis* argument is required but not used.
         """
         tz = unit
@@ -1862,7 +1862,8 @@ def convert(value, unit, axis):
     @staticmethod
     def default_units(x, axis):
         """
-        Return the tzinfo instance of *x* or of its first element, or None
+        Return the `~datetime.tzinfo` instance of *x* or of its first element,
+        or None
         """
         if isinstance(x, np.ndarray):
             x = x.ravel()
diff --git a/lib/matplotlib/dviread.py b/lib/matplotlib/dviread.py
index ab61fb8d5e35..cbd3b542a003 100644
--- a/lib/matplotlib/dviread.py
+++ b/lib/matplotlib/dviread.py
@@ -115,7 +115,7 @@ def glyph_name_or_index(self):
         glyph using FT_Load_Glyph/load_glyph.
 
         If :file:`pdftex.map` specifies no encoding, the indices directly map
-        to the font's "native" charmap; glyphs should directly loaded using
+        to the font's "native" charmap; glyphs should directly load using
         FT_Load_Char/load_char after selecting the native charmap.
         """
         entry = self._get_pdftexmap_entry()
@@ -1013,7 +1013,7 @@ def _parse_enc(path):
 
     Parameters
     ----------
-    path : os.PathLike
+    path : `os.PathLike`
 
     Returns
     -------
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
index 580a8e7df59d..6c18ba1a643e 100644
--- a/lib/matplotlib/figure.py
+++ b/lib/matplotlib/figure.py
@@ -467,9 +467,9 @@ def add_artist(self, artist, clip=False):
         """
         Add an `.Artist` to the figure.
 
-        Usually artists are added to Axes objects using `.Axes.add_artist`;
-        this method can be used in the rare cases where one needs to add
-        artists directly to the figure instead.
+        Usually artists are added to `~.axes.Axes` objects using
+        `.Axes.add_artist`; this method can be used in the rare cases where
+        one needs to add artists directly to the figure instead.
 
         Parameters
         ----------
@@ -501,7 +501,7 @@ def add_artist(self, artist, clip=False):
     @_docstring.dedent_interpd
     def add_axes(self, *args, **kwargs):
         """
-        Add an Axes to the figure.
+        Add an `~.axes.Axes` to the figure.
 
         Call signatures::
 
@@ -511,8 +511,9 @@ def add_axes(self, *args, **kwargs):
         Parameters
         ----------
         rect : tuple (left, bottom, width, height)
-            The dimensions (left, bottom, width, height) of the new Axes. All
-            quantities are in fractions of figure width and height.
+            The dimensions (left, bottom, width, height) of the new
+            `~.axes.Axes`. All quantities are in fractions of figure width and
+            height.
 
         projection : {None, 'aitoff', 'hammer', 'lambert', 'mollweide', \
 'polar', 'rectilinear', str}, optional
@@ -861,13 +862,13 @@ def subplots(self, nrows=1, ncols=1, *, sharex=False, sharey=False,
             axes[0, 0].plot(x, y)
             axes[1, 1].scatter(x, y)
 
-            # Share a X axis with each column of subplots
+            # Share an X-axis with each column of subplots
             fig.subplots(2, 2, sharex='col')
 
-            # Share a Y axis with each row of subplots
+            # Share a Y-axis with each row of subplots
             fig.subplots(2, 2, sharey='row')
 
-            # Share both X and Y axes with all subplots
+            # Share both X- and Y-axes with all subplots
             fig.subplots(2, 2, sharex='all', sharey='all')
 
             # Note that this is the same as
@@ -1235,7 +1236,7 @@ def colorbar(
             cbar.solids.set_edgecolor("face")
             draw()
 
-        However this has negative consequences in other circumstances, e.g.
+        However, this has negative consequences in other circumstances, e.g.
         with semi-transparent images (alpha < 1) and colorbar extensions;
         therefore, this workaround is not used by default (see issue #1188).
         """
@@ -1478,7 +1479,7 @@ def add_gridspec(self, nrows=1, ncols=1, **kwargs):
             Number of rows in grid.
 
         ncols : int, default: 1
-            Number or columns in grid.
+            Number of columns in grid.
 
         Returns
         -------
@@ -1700,7 +1701,7 @@ def get_tightbbox(self, renderer=None, bbox_extra_artists=None):
         Parameters
         ----------
         renderer : `.RendererBase` subclass
-            renderer that will be used to draw the figures (i.e.
+            Renderer that will be used to draw the figures (i.e.
             ``fig.canvas.get_renderer()``)
 
         bbox_extra_artists : list of `.Artist` or ``None``
@@ -2189,7 +2190,7 @@ def _redo_transform_rel_fig(self, bbox=None):
         ----------
         bbox : bbox or None
             If not None, then the bbox is used for relative bounding box.
-            Otherwise it is calculated from the subplotspec.
+            Otherwise, it is calculated from the subplotspec.
         """
         if bbox is not None:
             self.bbox_relative.p0 = bbox.p0
@@ -2536,9 +2537,9 @@ def set_layout_engine(self, layout=None, **kwargs):
             - 'none' removes layout engine.
 
             If `None`, the behavior is controlled by :rc:`figure.autolayout`
-            (which if `True` behaves as if 'tight' were passed) and
+            (which if `True` behaves as if 'tight' was passed) and
             :rc:`figure.constrained_layout.use` (which if `True` behaves as if
-            'constrained' were passed).  If both are `True`,
+            'constrained' was passed).  If both are `True`,
             :rc:`figure.autolayout` takes priority.
 
             Users and libraries can define their own layout engines and pass
@@ -3297,7 +3298,7 @@ def ginput(self, n=1, timeout=30, show_clicks=True,
             clicks until the input is terminated manually.
         timeout : float, default: 30 seconds
             Number of seconds to wait before timing out. If zero or negative
-            will never timeout.
+            will never time out.
         show_clicks : bool, default: True
             If True, show a red cross at the location of each click.
         mouse_add : `.MouseButton` or None, default: `.MouseButton.LEFT`
@@ -3316,7 +3317,7 @@ def ginput(self, n=1, timeout=30, show_clicks=True,
         -----
         The keyboard can also be used to select points in case your mouse
         does not have one or more of the buttons.  The delete and backspace
-        keys act like right clicking (i.e., remove last point), the enter key
+        keys act like right-clicking (i.e., remove last point), the enter key
         terminates input and any other key (not already used by the window
         manager) selects a point.
         """
diff --git a/lib/matplotlib/font_manager.py b/lib/matplotlib/font_manager.py
index 046c3215f301..57f21b79c85c 100644
--- a/lib/matplotlib/font_manager.py
+++ b/lib/matplotlib/font_manager.py
@@ -558,7 +558,7 @@ class FontProperties:
       'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy',
       'extra bold', 'black'. Default: :rc:`font.weight`
 
-    - size: Either an relative value of 'xx-small', 'x-small',
+    - size: Either a relative value of 'xx-small', 'x-small',
       'small', 'medium', 'large', 'x-large', 'xx-large' or an
       absolute font size, e.g., 10. Default: :rc:`font.size`
 
@@ -719,7 +719,7 @@ def get_fontconfig_pattern(self):
 
     def set_family(self, family):
         """
-        Change the font family.  May be either an alias (generic name
+        Change the font family.  Can be either an alias (generic name
         is CSS parlance), such as: 'serif', 'sans-serif', 'cursive',
         'fantasy', or 'monospace', a real font name or a list of real
         font names.  Real font names are not supported when
@@ -817,8 +817,8 @@ def set_size(self, size):
         ----------
         size : float or {'xx-small', 'x-small', 'small', 'medium', \
 'large', 'x-large', 'xx-large'}, default: :rc:`font.size`
-            If float, the font size in points. The string values denote sizes
-            relative to the default font size.
+            If a float, the font size in points. The string values denote
+            sizes relative to the default font size.
         """
         if size is None:
             size = mpl.rcParams['font.size']
@@ -987,7 +987,7 @@ class FontManager:
     font is returned.
     """
     # Increment this version number whenever the font cache data
-    # format or behavior has changed and requires a existing font
+    # format or behavior has changed and requires an existing font
     # cache files to be rebuilt.
     __version__ = 330
 
@@ -1224,7 +1224,7 @@ def findfont(self, prop, fontext='ttf', directory=None,
             If given, only search this directory and its subdirectories.
 
         fallback_to_default : bool
-            If True, will fallback to the default font family (usually
+            If True, will fall back to the default font family (usually
             "DejaVu Sans" or "Helvetica") if the first lookup hard-fails.
 
         rebuild_if_missing : bool
@@ -1294,7 +1294,7 @@ def _find_fonts_by_props(self, prop, fontext='ttf', directory=None,
             If given, only search this directory and its subdirectories.
 
         fallback_to_default : bool
-            If True, will fallback to the default font family (usually
+            If True, will fall back to the default font family (usually
             "DejaVu Sans" or "Helvetica") if none of the families were found.
 
         rebuild_if_missing : bool
@@ -1311,7 +1311,7 @@ def _find_fonts_by_props(self, prop, fontext='ttf', directory=None,
         -----
         This is an extension/wrapper of the original findfont API, which only
         returns a single font for given font properties. Instead, this API
-        returns an dict containing multiple fonts and their filepaths
+        returns a dict containing multiple fonts and their filepaths
         which closely match the given font properties.  Since this internally
         uses the original API, there's no change to the logic of performing the
         nearest neighbor search.  See `findfont` for more details.
diff --git a/lib/matplotlib/gridspec.py b/lib/matplotlib/gridspec.py
index 09212df7e490..94ae9ba35fc5 100644
--- a/lib/matplotlib/gridspec.py
+++ b/lib/matplotlib/gridspec.py
@@ -538,17 +538,17 @@ class SubplotSpec:
 
     .. note::
 
-        Likely, you'll never instantiate a `SubplotSpec` yourself. Instead you
-        will typically obtain one from a `GridSpec` using item-access.
+        Likely, you will never instantiate a `SubplotSpec` yourself. Instead,
+        you will typically obtain one from a `GridSpec` using item-access.
 
     Parameters
     ----------
     gridspec : `~matplotlib.gridspec.GridSpec`
         The GridSpec, which the subplot is referencing.
     num1, num2 : int
-        The subplot will occupy the num1-th cell of the given
-        gridspec.  If num2 is provided, the subplot will span between
-        num1-th cell and num2-th cell *inclusive*.
+        The subplot will occupy the *num1*-th cell of the given
+        *gridspec*.  If *num2* is provided, the subplot will span between
+        *num1*-th cell and *num2*-th cell **inclusive**.
 
         The index starts from 0.
     """
@@ -710,7 +710,7 @@ def subgridspec(self, nrows, ncols, **kwargs):
             Number of rows in grid.
 
         ncols : int
-            Number or columns in grid.
+            Number of columns in grid.
 
         Returns
         -------
diff --git a/lib/matplotlib/image.py b/lib/matplotlib/image.py
index 573b7ef053e0..22ce5d58fa05 100644
--- a/lib/matplotlib/image.py
+++ b/lib/matplotlib/image.py
@@ -1510,7 +1510,7 @@ def imread(fname, format=None):
     format : str, optional
         The image file format assumed for reading the data.  The image is
         loaded as a PNG file if *format* is set to "png", if *fname* is a path
-        or opened file with a ".png" extension, or if it is an URL.  In all
+        or opened file with a ".png" extension, or if it is a URL.  In all
         other cases, *format* is ignored and the format is auto-detected by
         `PIL.Image.open`.
 
diff --git a/lib/matplotlib/layout_engine.py b/lib/matplotlib/layout_engine.py
index 4f3e7a9ce95c..11a0dc8c4fb9 100644
--- a/lib/matplotlib/layout_engine.py
+++ b/lib/matplotlib/layout_engine.py
@@ -54,7 +54,7 @@ class LayoutEngine:
     3. override `LayoutEngine.execute` with your implementation
 
     """
-    # override these is sub-class
+    # override these in subclass
     _adjust_compatible = None
     _colorbar_gridspec = None
 
@@ -103,7 +103,7 @@ class PlaceHolderLayoutEngine(LayoutEngine):
     """
     This layout engine does not adjust the figure layout at all.
 
-    The purpose of this `.LayoutEngine` is to act as a place holder when the
+    The purpose of this `.LayoutEngine` is to act as a placeholder when the
     user removes a layout engine to ensure an incompatible `.LayoutEngine` can
     not be set later.