improve docstring of Axes.scatter

timhoffm · timhoffm · commit 6450fd006949 · 2018-01-13T17:48:09.000+01:00
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -3951,74 +3951,75 @@ def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
                 verts=None, edgecolors=None,
                 **kwargs):
         """
-        Make a scatter plot of *x* vs *y*.
-
-        Marker size is scaled by *s* and marker color is mapped to *c*.
+        A scatter plot of *y* vs *x* with varying marker size *s* and/or
+        color *c*.
 
         Parameters
         ----------
         x, y : array_like, shape (n, )
-            Input data
+            The data positions.
 
         s : scalar or array_like, shape (n, ), optional
-            Size in points**2.
+            The marker size in points**2.
             Default is ``rcParams['lines.markersize'] ** 2``.
 
         c : color, sequence, or sequence of color, optional, default: 'b'
-            *c* can be a single color format string, or a sequence of color
-            specifications of length `N`, or a sequence of `N` numbers to be
-            mapped to colors using the `cmap` and `norm` specified via kwargs
-            (see below). Note that `c` should not be a single numeric RGB or
-            RGBA sequence because that is indistinguishable from an array of
-            values to be colormapped.  `c` can be a 2-D array in which the
-            rows are RGB or RGBA, however, including the case of a single
-            row to specify the same color for all points.
+            The marker color. Possible values:
+
+            - A single color format string.
+            - A sequence of color specifications of length n.
+            - A sequence of n numbers to be mapped to colors using *cmap* and
+              *norm*.
+            - A 2-D array in which the rows are RGB or RGBA.
+
+            Note that *c* should not be a single numeric RGB or RGBA sequence
+            because that is indistinguishable from an array of values to be
+            colormapped. If you want to specify the same RGB or RGBA value for
+            all points, use a 2-D array with a single row.
 
         marker : `~matplotlib.markers.MarkerStyle`, optional, default: 'o'
-            See `~matplotlib.markers` for more information on the different
-            styles of markers scatter supports. *marker* can be either
-            an instance of the class or the text shorthand for a particular
-            marker.
+            The marker style. *marker* can be either an instance of the class
+            or the text shorthand for a particular marker.
+            See `~matplotlib.markers` for more information marker styles.
 
         cmap : `~matplotlib.colors.Colormap`, optional, default: None
-            A `~matplotlib.colors.Colormap` instance or registered name.
-            *cmap* is only used if *c* is an array of floats. If ``None``,
-            defaults to rc ``image.cmap``.
+            A `.Colormap` instance or registered colormap name. *cmap* is only
+            used if *c* is an array of floats. If ``None``, defaults to rc
+            ``image.cmap``.
 
         norm : `~matplotlib.colors.Normalize`, optional, default: None
-            A `~matplotlib.colors.Normalize` instance is used to scale
-            luminance data to 0, 1. *norm* is only used if *c* is an array of
-            floats. If ``None``, use the default `.colors.Normalize`.
+            A `~.Normalize` instance is used to scale luminance data to 0, 1.
+            *norm* is only used if *c* is an array of floats. If *None*, use
+            the default `.colors.Normalize`.
 
         vmin, vmax : scalar, optional, default: None
             *vmin* and *vmax* are used in conjunction with *norm* to normalize
-            luminance data. If either are ``None``, the min and max of the
-            color array is used.  Note if you pass a *norm* instance, your
-            settings for *vmin* and *vmax* will be ignored.
+            luminance data. If None, the respective min and max of the color
+            array is used. *vmin* and *vmax* are ignored if you pass a *norm*
+            instance.
 
         alpha : scalar, optional, default: None
-            The alpha blending value, between 0 (transparent) and 1 (opaque)
+            The alpha blending value, between 0 (transparent) and 1 (opaque).
 
         linewidths : scalar or array_like, optional, default: None
-            If ``None``, defaults to ``(lines.linewidth,)``.
+            The linewidth of the marker edges. Note: The default *edgecolors*
+            is 'face'. You may want to change this as well.
+            If *None*, defaults to rcParams ``lines.linewidth``.
 
         verts : sequence of (x, y), optional
-            If *marker* is ``None``, these vertices will be used to
-            construct the marker.  The center of the marker is located
-            at (0,0) in normalized units.  The overall marker is rescaled
-            by *s*.
-
-        edgecolors : color or sequence of color, optional, default: None
-            If ``None``, defaults to 'face'.
+            If *marker* is *None*, these vertices will be used to construct
+            the marker.  The center of the marker is located at (0, 0) in
+            normalized units.  The overall marker is rescaled by *s*.
 
-            If 'face', the edge color will always be the same as
-            the face color.
+        edgecolors : color or sequence of color, optional, default: 'face'
+            The edge color of the marker. Possible values:
 
-            If 'none', the patch boundary will not
-            be drawn.
+            - 'face': The edge color will always be the same as the face color.
+            - 'none': No patch boundary will be drawn.
+            - A matplotib color.
 
-            For non-filled markers, the *edgecolors* kwarg
-            is ignored and forced to 'face' internally.
+            For non-filled markers, the *edgecolors* kwarg is ignored and
+            forced to 'face' internally.
 
         Returns
         -------
@@ -4036,14 +4037,14 @@ def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
         Notes
         -----
 
-        * The `plot` function will be faster for scatterplots where markers
+        * The `.plot` function will be faster for scatterplots where markers
           don't vary in size or color.
 
         * Any or all of *x*, *y*, *s*, and *c* may be masked arrays, in which
           case all masks will be combined and only unmasked points will be
           plotted.
 
-          Fundamentally, scatter works with 1-D arrays; *x*, *y*, *s*, and *c*
+        * Fundamentally, scatter works with 1-D arrays; *x*, *y*, *s*, and *c*
           may be input as 2-D arrays, but within scatter they will be
           flattened. The exception is *c*, which will be flattened only if its
           size matches the size of *x* and *y*.
