DOC: Improve stairs docstring

Author: timhoffm

galleries/plot_types/basic/stairs.py

@@ -2,7 +2,7 @@
 ==============
 stairs(values)
 ==============
-A stepwise constant function as a line with bounding edges or a filled plot.
+Draw a stepwise constant function as a line or a filled plot.
 
 See `~matplotlib.axes.Axes.stairs` when plotting :math:`y` between
 :math:`(x_i, x_{i+1})`. For plotting :math:`y` at :math:`x`, see

lib/matplotlib/axes/_axes.py

@@ -7104,16 +7104,19 @@ 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 stepwise constant function as a line with bounding edges
-        or a filled plot.
+        Draw a stepwise constant function as a line or a filled plot.
+
+        *edges* define the x-axis positions of the steps. *values* the function values
+        between these steps. Depending on *fill*, the function is drawn either as a
+        continuous line with vertical segments at the edges, or as a filled area.
 
         Parameters
         ----------
         values : array-like
             The step heights.
 
         edges : array-like
-            The edge positions, with ``len(edges) == len(vals) + 1``,
+            The step positions, with ``len(edges) == len(vals) + 1``,
             between which the curve takes on vals values.
 
         orientation : {'vertical', 'horizontal'}, default: 'vertical'