DOCS: use "or list thereof" for collection types

brunobeltran · brunobeltran · commit 33498df8bc8a · 2020-06-05T19:35:01.000-07:00
diff --git a/lib/matplotlib/collections.py b/lib/matplotlib/collections.py
@@ -93,21 +93,17 @@ def __init__(self,
                  **kwargs
                  ):
         """
-        For all "plural" parameters, the type listed is the expected type when
-        passing a single value to be used for the whole collection. For any of
-        these inputs, a Sequence of the specified type is also allowed.
-
         Parameters
         ----------
-        edgecolors : color, default: :rc:`patch.edgecolor`
+        edgecolors : color or list of colors, default: :rc:`patch.edgecolor`
             Edge color for each patch making up the collection. The special
             value 'face' can be passed to make the edgecolor match the
             facecolor.
-        facecolors : color, default: :rc:`patch.facecolor`
+        facecolors : color or list of colors, default: :rc:`patch.facecolor`
             Face color for each patch making up the collection.
-        linewidths : float, default: :rc:`patch.linewidth`
+        linewidths : float or list of floats, default: :rc:`patch.linewidth`
             Line width for each patch making up the collection.
-        linestyles : str or tuple, default: 'solid'
+        linestyles : str or tuple or list thereof, default: 'solid'
             Valid strings are ['solid', 'dashed', 'dashdot', 'dotted', '-',
             '--', '-.', ':']. Dash tuples should be of the form::
 
@@ -120,10 +116,10 @@ def __init__(self,
             Style to use for capping lines for all paths in the collection.
         joinstyle : str, default: :rc:`patch.joinstyle`
             Style to use for joining lines for all paths in the collection.
-        antialiaseds : bool, default: :rc:`patch.antialiased`
+        antialiaseds : bool or list of bool, default: :rc:`patch.antialiased`
             Whether each pach in the collection should be drawn with
             antialiasing.
-        offsets : (float, float), default: (0, 0)
+        offsets : (float, float) or list thereof, default: (0, 0)
             A vector by which to translate each patch after rendering (default
             is no translation). The translation is performed in screen (pixel)
             coordinates (i.e. after the Artist's transform is applied).
@@ -152,7 +148,7 @@ def __init__(self,
             other hand, if it is greater than 0, then we instead check if the
             test point is contained in a stroke of width ``2*pickradius``
             following any of the Paths in the Collection.
-        urls : str, default: None
+        urls : list of str, optional, default: None
             A URL for each patch to link to once drawn. Currently only works
             for the SVG backend. See :doc:`/gallery/misc/hyperlinks_sgskip` for
             examples.
@@ -472,7 +468,7 @@ def set_urls(self, urls):
         """
         Parameters
         ----------
-        urls : list of str or None
+        urls : sequence of str or None
 
         Notes
         -----
@@ -594,7 +590,7 @@ def set_linewidth(self, lw):
 
         Parameters
         ----------
-        lw : float or sequence of floats
+        lw : float or list of floats
         """
         if lw is None:
             lw = mpl.rcParams['patch.linewidth']
@@ -629,8 +625,11 @@ def set_linestyle(self, ls):
 
         Parameters
         ----------
-        ls : {'-', '--', '-.', ':', '', (offset, on-off-seq), ...}
-            The line style.
+        ls : str or tuple or list thereof
+            Valid values for individual linestyles include {'-', '--', '-.',
+            ':', '', (offset, on-off-seq)}. See
+            `~.matplotlib.lines.Line2D.set_linestyle` for a complete
+            description.
         """
         try:
             if isinstance(ls, str):
@@ -660,7 +659,7 @@ def set_capstyle(self, cs):
         Parameters
         ----------
         cs : {'butt', 'round', 'projecting'}
-            The capstyle
+            The capstyle.
         """
         mpl.rcsetup.validate_capstyle(cs)
         self._capstyle = cs
@@ -675,7 +674,7 @@ def set_joinstyle(self, js):
         Parameters
         ----------
         js : {'miter', 'round', 'bevel'}
-            The joinstyle
+            The joinstyle.
         """
         mpl.rcsetup.validate_joinstyle(js)
         self._joinstyle = js
@@ -1019,9 +1018,10 @@ def legend_elements(self, prop="colors", num="auto",
 
         Returns
         -------
-        tuple (handles, labels)
-            with *handles* being a list of `.Line2D`  objects
-            and *labels* a matching list of strings.
+        handles : list of `.Line2D`
+            Visual representation of each element of the legend.
+        labels : list of str
+            The string label for element of the legend.
         """
         handles = []
         labels = []
@@ -1102,11 +1102,11 @@ def __init__(self, verts, sizes=None, closed=True, **kwargs):
         """
         Parameters
         ----------
-        verts : sequence
+        verts : sequence of array-like
             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
+        sizes : array-like of float, 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
@@ -1302,11 +1302,21 @@ class AsteriskPolygonCollection(RegularPolyCollection):
 
 
 class LineCollection(Collection):
-    """
-    Collection of 2D lines. Each line may have an arbitrary number of segments.
+    r"""
+    Represents a sequence of `~.lines.Line2D`\s that should be drawn together.
+
+    This class extends `.Collection` to represent a sequence of
+    `~.lines.Line2D`\s instead of just a sequence of `~.patches.Patch`\s.
+    Just as in `.Collection`, each property of a *LineCollection* may be either
+    a single value or a list of values. This list is then used cyclically for
+    each element of the LineCollection, so the property of the ``i``\th element
+    of the collection is::
 
-    Relevant parameters default to their ``'lines'`` values in
-    `~.matplotlib.rcParams` instead of their ``'patch'`` values.
+      prop[i % len(prop)]
+
+    A *LineCollection*'s properties default to their ``'lines'`` values in
+    `~.matplotlib.rcParams` instead of their ``'patch'`` values, and the
+    property *colors* is added in place of *edgecolors*.
     """
 
     _edge_default = True
@@ -1326,32 +1336,25 @@ def __init__(self, segments,     # Can be None.
                  **kwargs
                  ):
         """
-        Except for *segments*, the type listed below is the expected type when
-        passing a single value to be used for the whole collection. A Sequence
-        of the specified type is also allowed, in which case the property for
-        the ``i``th element of the collection will be::
-
-            prop[i % len(prop)]
-
         Parameters
         ----------
-        segments
+        segments: sequence of array-like
             A sequence of (*line0*, *line1*, *line2*), where::
 
                 linen = (x0, y0), (x1, y1), ... (xm, ym)
 
             or the equivalent numpy array with two columns. Each line
             can have a different number of segments.
-        linewidths : float, default: :rc:`lines.linewidth`
+        linewidths : float or list of float, default: :rc:`lines.linewidth`
             The width of each line in points.
-        colors : color, default: :rc:`lines.color`
+        colors : color or list of color, default: :rc:`lines.color`
             A sequence of RGBA tuples (e.g., arbitrary color strings, etc, not
             allowed).
-        antialiaseds : default: :rc:`lines.antialiased`
+        antialiaseds : bool or list of bool, default: :rc:`lines.antialiased`
             Whether to use antialiasing for each line.
         zorder : int, default: 2
            zorder of the lines once drawn.
-        facecolors : default: 'none'
+        facecolors : color or list of color, default: 'none'
            The facecolors of the LineCollection.
            Setting to a value other than 'none' will lead to each line being
            "filled in" as if there was an implicit line segment joining the
@@ -1492,19 +1495,19 @@ def __init__(self,
         linelength : float, default: 1
             The total height of the marker (i.e. the marker stretches from
             ``lineoffset - linelength/2`` to ``lineoffset + linelength/2``).
-        linewidth : float, default: :rc:`lines.linewidth`
+        linewidth : float or list thereof, default: :rc:`lines.linewidth`
             The line width of the event lines, in points.
         color : color or list of colors, default: :rc:`lines.color`
             The color of the event lines.
-        linestyle : str or tuple, default: 'solid'
+        linestyle : str or tuple or list thereof, default: 'solid'
             Valid strings are ['solid', 'dashed', 'dashdot', 'dotted',
             '-', '--', '-.', ':']. Dash tuples should be of the form::
 
                 (offset, onoffseq),
 
             where *onoffseq* is an even length tuple of on and off ink
             in points.
-        antialiased : bool, default: :rc:`lines.antialiased`
+        antialiased : bool or list thereof, default: :rc:`lines.antialiased`
             Whether to use antialiasing for drawing the lines.
         **kwargs
             Forwarded to `.LineCollection`.
