StepPatch and stairs() docstring improvements.

Author: timhoffm

lib/matplotlib/axes/_axes.py

@@ -6744,24 +6744,27 @@ def hist(self, x, bins=None, range=None, density=False, weights=None,
     def stairs(self, values, edges=None, *,
                orientation='vertical', baseline=0, fill=False, **kwargs):
         """
-        A histogram-like line or filled plot.
+        A stepwise constant line or filled plot.
 
         Parameters
         ----------
         values : array-like
-            An array of y-values.
+            The step heights.
 
-        edges : array-like, default: ``range(len(vals)+1)``
-            A array of x-values, with ``len(edges) == len(vals) + 1``,
+        edges : array-like
+            The edge positions, with ``len(edges) == len(vals) + 1``,
             between which the curve takes on vals values.
 
         orientation : {'vertical', 'horizontal'}, default: 'vertical'
+            The direction of the steps. Vertical means that *values* are along
+            the y-axis, and edges are along the x-axis.
 
         baseline : float or None, default: 0
             Determines starting value of the bounding edges or when
             ``fill=True``, position of lower edge.
 
         fill : bool, default: False
+            Whether the area under the step curve should be filled.
 
         Returns
         -------

lib/matplotlib/patches.py

@@ -990,7 +990,11 @@ def set_path(self, path):
 
 
 class StepPatch(PathPatch):
-    """An unclosed step path patch."""
+    """
+    A path patch describing a stepwise constant function.
+
+    The path is unclosed. It starts and stops at baseline.
+    """
 
     @docstring.dedent_interpd
     def __init__(self, values, edges, *,
@@ -999,13 +1003,15 @@ def __init__(self, values, edges, *,
         Parameters
         ----------
         values : array-like
-            An array of y-values.
+            The step heights.
 
         edges : array-like
-            A array of x-value edges, with ``len(edges) == len(vals) + 1``,
+            The edge positions, with ``len(edges) == len(vals) + 1``,
             between which the curve takes on vals values.
 
         orientation : {'vertical', 'horizontal'}, default: 'vertical'
+            The direction of the steps. Vertical means that *values* are along
+            the y-axis, and edges are along the x-axis.
 
         baseline : float or None, default: 0
             Determines starting value of the bounding edges or when