Improve docstring of triplot() and PatchCollection

As part of matplotlib#10148: Docstring update for Axes.triplot() and
PatchCollection.

Author: timhoffm

lib/matplotlib/collections.py

@@ -1780,29 +1780,34 @@ class PatchCollection(Collection):
     """
     A generic collection of patches.
 
-    This makes it easier to assign a colormap to a heterogeneous
+    PatchCollection draws faster than a large number of equivalent individual
+    Patches. It also makes it easier to assign a colormap to a heterogeneous
     collection of patches.
-
-    This also may improve plotting speed, since PatchCollection will
-    draw faster than a large number of patches.
     """
 
     def __init__(self, patches, match_original=False, **kwargs):
         """
-        *patches*
-            a sequence of Patch objects.  This list may include
+        Parameters
+        ----------
+        patches : list of `.Patch`
+            A sequence of Patch objects.  This list may include
             a heterogeneous assortment of different patch types.
 
-        *match_original*
+        match_original : bool, default: False
             If True, use the colors and linewidths of the original
             patches.  If False, new colors may be assigned by
             providing the standard collection arguments, facecolor,
             edgecolor, linewidths, norm or cmap.
 
-        If any of *edgecolors*, *facecolors*, *linewidths*, *antialiaseds* are
-        None, they default to their `.rcParams` patch setting, in sequence
-        form.
+        **kwargs
+            All other parameters are forwarded to `.Collection`.
 
+            If any of *edgecolors*, *facecolors*, *linewidths*, *antialiaseds*
+            are None, they default to their `.rcParams` patch setting, in
+            sequence form.
+
+        Notes
+        -----
         The use of `~matplotlib.cm.ScalarMappable` functionality is optional.
         If the `~matplotlib.cm.ScalarMappable` matrix ``_A`` has been set (via
         a call to `~.ScalarMappable.set_array`), at draw time a call to scalar

lib/matplotlib/tri/triplot.py

@@ -6,26 +6,27 @@
 
 def triplot(ax, *args, **kwargs):
     """
-    Draw a unstructured triangular grid as lines and/or markers.
+    Draw an unstructured triangular grid as lines and/or markers.
 
-    The triangulation to plot can be specified in one of two ways; either::
+    Call signatures::
 
       triplot(triangulation, ...)
-
-    where triangulation is a `.Triangulation` object, or
-
-    ::
-
-      triplot(x, y, ...)
-      triplot(x, y, triangles, ...)
-      triplot(x, y, triangles=triangles, ...)
-      triplot(x, y, mask=mask, ...)
-      triplot(x, y, triangles, mask=mask, ...)
-
-    in which case a Triangulation object will be created.  See `.Triangulation`
-    for a explanation of these possibilities.
-
-    The remaining args and kwargs are the same as for `~.Axes.plot`.
+      triplot(x, y, [triangles], *, [mask=mask], ...)
+
+    The triangular grid can be specified either by passing a `.Triangulation`
+    object as the first parameter, or by passing the points *x*, *y* and
+    optionally the *triangles* and a *mask*. If neither of *triangulation* or
+    *triangles* are given, the triangulation is calculated on the fly.
+
+    Parameters
+    ----------
+    triangulation : `.Triangulation`
+        An already created triangular grid.
+    x, y, triangles, mask
+        Parameters defining the triangular grid. See `.Triangulation`.
+        This is mutually exclusive with specifying *triangulation*.
+    other_parameters
+        All other args and kwargs are forwarded to `~.Axes.plot`.
 
     Returns
     -------