From ea6fd28b68a6223e62c11496682e8149cca0f296 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Fri, 29 Nov 2019 01:23:11 +0100
Subject: [PATCH] Update docs of PolyCollection

---
 lib/matplotlib/artist.py      |  4 +-
 lib/matplotlib/cm.py          |  8 +--
 lib/matplotlib/collections.py | 93 +++++++++++++++++++++--------------
 lib/matplotlib/patches.py     |  2 +-
 4 files changed, 64 insertions(+), 43 deletions(-)

diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py
index 9e0af07c4823..d871b85236af 100644
--- a/lib/matplotlib/artist.py
+++ b/lib/matplotlib/artist.py
@@ -802,7 +802,7 @@ def get_visible(self):
         return self._visible
 
     def get_animated(self):
-        """Return the animated state."""
+        """Return whether the artist is animated."""
         return self._animated
 
     def get_in_layout(self):
@@ -1072,7 +1072,7 @@ def sticky_edges(self):
         return self._sticky_edges
 
     def update_from(self, other):
-        'Copy properties from *other* to *self*.'
+        """"Copy properties from *other* to *self*."""
         self._transform = other._transform
         self._transformSet = other._transformSet
         self._visible = other._visible
diff --git a/lib/matplotlib/cm.py b/lib/matplotlib/cm.py
index 54c45264dcc3..46ff8f5eeacb 100644
--- a/lib/matplotlib/cm.py
+++ b/lib/matplotlib/cm.py
@@ -256,15 +256,17 @@ def set_array(self, A):
         self.update_dict['array'] = True
 
     def get_array(self):
-        'Return the array'
+        """Return the data array."""
         return self._A
 
     def get_cmap(self):
-        'return the colormap'
+        """Return the `.Colormap` instance."""
         return self.cmap
 
     def get_clim(self):
-        'return the min, max of the color limits for image scaling'
+        """
+        Return the values (min, max) that are mapped to the colormap limits.
+        """
         return self.norm.vmin, self.norm.vmax
 
     def set_clim(self, vmin=None, vmax=None):
diff --git a/lib/matplotlib/collections.py b/lib/matplotlib/collections.py
index 5871868c8fee..bf12758b8134 100644
--- a/lib/matplotlib/collections.py
+++ b/lib/matplotlib/collections.py
@@ -1051,22 +1051,24 @@ class PolyCollection(_CollectionWithSizes):
     @docstring.dedent_interpd
     def __init__(self, verts, sizes=None, closed=True, **kwargs):
         """
-        *verts* is a sequence of ( *verts0*, *verts1*, ...) where
-        *verts_i* is a sequence of *xy* tuples of vertices, or an
-        equivalent :mod:`numpy` array of shape (*nv*, 2).
-
-        *sizes* is *None* (default) or a sequence of floats that
-        scale the corresponding *verts_i*.  The scaling is applied
-        before the Artist master transform; if the latter is an identity
-        transform, then the overall scaling is such that if
-        *verts_i* specify a unit square, then *sizes_i* is the area
-        of that square in points^2.
-        If len(*sizes*) < *nv*, the additional values will be
-        taken cyclically from the array.
-
-        *closed*, when *True*, will explicitly close the polygon.
-
-        %(Collection)s
+        Parameters
+        ----------
+        verts : sequence
+            The sequence of polygons [*verts0*, *verts1*, ...] where each
+            element *verts_i* defines the vertices of polygon *i* as a 2D
+            array-like of of shape (M, 2).
+        sizes : array-like, default: None
+            Squared scaling factors for the polygons. The coordinates of each
+            polygon *verts_i* are multiplied by the square-root of the
+            corresponding entry in *sizes* (i.e., *sizes* specify the scaling
+            of areas). The scaling is applied before the Artist master
+            transform. If *sizes* is shorter than *verts*, the additional
+            values will be taken cyclically from the *sizes*.
+        closed : bool, default: True
+            Whether the polygon should be closed by adding a CLOSEPOLY
+            connection at the end.
+        **kwargs
+            %(Collection)s
         """
         Collection.__init__(self, **kwargs)
         self.set_sizes(sizes)
@@ -1074,7 +1076,19 @@ def __init__(self, verts, sizes=None, closed=True, **kwargs):
         self.stale = True
 
     def set_verts(self, verts, closed=True):
-        '''This allows one to delay initialization of the vertices.'''
+        """
+        Set the vertices of the polygons.
+
+        Parameters
+        ----------
+        verts : sequence
+            The sequence of polygons [*verts0*, *verts1*, ...] where each
+            element *verts_i* defines the vertices of polygon *i* as a 2D
+            array-like of of shape (M, 2).
+        closed : bool, default: True
+            Whether the polygon should be closed by adding a CLOSEPOLY
+            connection at the end.
+        """
         if isinstance(verts, np.ma.MaskedArray):
             verts = verts.astype(float).filled(np.nan)
             # This is much faster than having Path do it one at a time.
@@ -1122,13 +1136,14 @@ class BrokenBarHCollection(PolyCollection):
     @docstring.dedent_interpd
     def __init__(self, xranges, yrange, **kwargs):
         """
-        *xranges*
-            sequence of (*xmin*, *xwidth*)
-
-        *yrange*
-            *ymin*, *ywidth*
-
-        %(Collection)s
+        Parameters
+        ----------
+        xranges : sequence of (float, float)
+            The sequence of (left-edge-position, width) pairs for each bar.
+        yrange : (float, float)
+            The (lower-edge, height) common to all bars.
+        **kwargs
+            %(Collection)s
         """
         ymin, ywidth = yrange
         ymax = ymin + ywidth
@@ -1162,7 +1177,7 @@ def span_where(x, ymin, ymax, where, **kwargs):
 
 
 class RegularPolyCollection(_CollectionWithSizes):
-    """Draw a collection of regular polygons with *numsides*."""
+    """A collection of n-sided regular polygons."""
 
     _path_generator = mpath.Path.unit_regular_polygon
     _factor = np.pi ** (-1/2)
@@ -1174,20 +1189,24 @@ def __init__(self,
                  sizes=(1,),
                  **kwargs):
         """
-        *numsides*
-            the number of sides of the polygon
-
-        *rotation*
-            the rotation of the polygon in radians
-
-        *sizes*
-            gives the area of the circle circumscribing the
-            regular polygon in points^2
+        Parameters
+        ----------
+        numsides : int
+            The number of sides of the polygon.
+        rotation : float
+            The rotation of the polygon in radians.
+        sizes : tuple of float
+            The area of the circle circumscribing the polygon in points^2.
 
-        %(Collection)s
+        Other Parameters
+        ----------------
+        **kwargs
+            Other keyword arguments.
+            %(Collection)s
 
-        Example: see :doc:`/gallery/event_handling/lasso_demo` for a
-        complete example::
+        Examples
+        --------
+        See :doc:`/gallery/event_handling/lasso_demo` for a complete example::
 
             offsets = np.random.rand(20, 2)
             facecolors = [cm.jet(x) for x in np.random.rand(20)]
diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py
index 3b59c235430f..6c40a8a1140b 100644
--- a/lib/matplotlib/patches.py
+++ b/lib/matplotlib/patches.py
@@ -232,7 +232,7 @@ def contains_points(self, points, radius=None):
                                                radius)
 
     def update_from(self, other):
-        """Updates this `.Patch` from the properties of *other*."""
+        # docstring inherited.
         artist.Artist.update_from(self, other)
         # For some properties we don't need or don't want to go through the
         # getters/setters, so we just copy them directly.