Improve plot() docstring.

anntzer · anntzer · commit b0e0054852cd · 2019-02-02T15:04:39.000+01:00
- Mark `x`, `y`, `fmt` as positional-only.
- Scalar values are not broadcasted against non-scalar values, despite
  what the docstring claims.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -1335,7 +1335,7 @@ def plot(self, *args, scalex=True, scaley=True, data=None, **kwargs):
 
         Call signatures::
 
-            plot([x], y, [fmt], data=None, **kwargs)
+            plot([x], y, [fmt], *, data=None, **kwargs)
             plot([x], y, [fmt], [x2], y2, [fmt2], ..., **kwargs)
 
         The coordinates of the points or line nodes are given by *x*, *y*.
@@ -1359,6 +1359,7 @@ def plot(self, *args, scalex=True, scaley=True, data=None, **kwargs):
 
         When conflicting with *fmt*, keyword arguments take precedence.
 
+
         **Plotting labelled data**
 
         There's a convenient way for plotting objects with labelled data (i.e.
@@ -1406,19 +1407,19 @@ def plot(self, *args, scalex=True, scaley=True, data=None, **kwargs):
         Alternatively, you can also change the style cycle using the
         'axes.prop_cycle' rcParam.
 
+
         Parameters
         ----------
         x, y : array-like or scalar
             The horizontal / vertical coordinates of the data points.
-            *x* values are optional. If not given, they default to
-            ``[0, ..., N-1]``.
+            *x* values are optional and default to `range(len(y))`.
 
-            Commonly, these parameters are arrays of length N. However,
-            scalars are supported as well (equivalent to an array with
-            constant value).
+            Commonly, these parameters are 1D arrays.
 
-            The parameters can also be 2-dimensional. Then, the columns
-            represent separate data sets.
+            They can also be scalars, or two-dimensional (in that case, the
+            columns represent separate data sets).
+
+            These arguments cannot be passed as keywords.
 
         fmt : str, optional
             A format string, e.g. 'ro' for red circles. See the *Notes*
@@ -1428,6 +1429,8 @@ def plot(self, *args, scalex=True, scaley=True, data=None, **kwargs):
             basic line properties. All of these and more can also be
             controlled by keyword arguments.
 
+            This argument cannot be passed as keyword.
+
         data : indexable object, optional
             An object with labelled data. If given, provide the label names to
             plot in *x* and *y*.
