From a8d8915de24ad2ac3706926bf790a85a03e426ae Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Fri, 15 Mar 2024 10:15:09 +0100
Subject: [PATCH 1/2] DOC: Add summary lines to plot types.

IMHO it's meaningful to give a one-sentence summary on the individual
pages, e.g. at
https://matplotlib.org/stable/plot_types/basic/plot.html#sphx-glr-plot-types-basic-plot-py

> Plot y versus x as lines and/or markers.
>
> See `plot`.

is more helpful than just

> See `plot`.

Users can already decide if that's the correct function for them and
whether it's worth following the link. Also, the first sentence is used
in the tooltip on the index page, where the current "See ..." is not
helpful.

I believe it's ok to just copy the text. Automatic insertion or check
for consistency are not worth the added effort. First, these summary
lines change rarely. Second, even if we improve the method summary and
forget to udpate here, nothing really bad happens; we've maybe a
slightly less optimal description here, but that's still way better than
no description at all.

Semi-OT: I changed the barbs summary from

> Plot a 2D field of barbs.

to

> Plot a 2D field of wind barbs.

because, AFAIK these are only used for wind, and that makes the context
more clear. People outside of metrology may not know what barbs are
so giving that extra context is reasonable.
---
 galleries/plot_types/arrays/barbs.py             | 1 +
 galleries/plot_types/arrays/contour.py           | 1 +
 galleries/plot_types/arrays/contourf.py          | 1 +
 galleries/plot_types/arrays/imshow.py            | 1 +
 galleries/plot_types/arrays/pcolormesh.py        | 1 +
 galleries/plot_types/arrays/quiver.py            | 1 +
 galleries/plot_types/arrays/streamplot.py        | 1 +
 galleries/plot_types/basic/fill_between.py       | 1 +
 galleries/plot_types/basic/plot.py               | 1 +
 galleries/plot_types/basic/scatter_plot.py       | 1 +
 galleries/plot_types/basic/stackplot.py          | 2 ++
 galleries/plot_types/basic/stairs.py             | 1 +
 galleries/plot_types/basic/stem.py               | 1 +
 galleries/plot_types/stats/boxplot_plot.py       | 1 +
 galleries/plot_types/stats/ecdf.py               | 1 +
 galleries/plot_types/stats/errorbar_plot.py      | 1 +
 galleries/plot_types/stats/eventplot.py          | 1 +
 galleries/plot_types/stats/hexbin.py             | 1 +
 galleries/plot_types/stats/hist2d.py             | 1 +
 galleries/plot_types/stats/hist_plot.py          | 1 +
 galleries/plot_types/stats/pie.py                | 1 +
 galleries/plot_types/stats/violin.py             | 1 +
 galleries/plot_types/unstructured/tricontour.py  | 1 +
 galleries/plot_types/unstructured/tricontourf.py | 1 +
 galleries/plot_types/unstructured/tripcolor.py   | 1 +
 galleries/plot_types/unstructured/triplot.py     | 1 +
 lib/matplotlib/quiver.py                         | 2 +-
 lib/matplotlib/stackplot.py                      | 2 +-
 28 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/galleries/plot_types/arrays/barbs.py b/galleries/plot_types/arrays/barbs.py
index 63e492869039..b007d9b875b8 100644
--- a/galleries/plot_types/arrays/barbs.py
+++ b/galleries/plot_types/arrays/barbs.py
@@ -2,6 +2,7 @@
 =================
 barbs(X, Y, U, V)
 =================
+Plot a 2D field of wind barbs.
 
 See `~matplotlib.axes.Axes.barbs`.
 """
diff --git a/galleries/plot_types/arrays/contour.py b/galleries/plot_types/arrays/contour.py
index fe79c18d2b58..1bf8d71d482b 100644
--- a/galleries/plot_types/arrays/contour.py
+++ b/galleries/plot_types/arrays/contour.py
@@ -2,6 +2,7 @@
 ================
 contour(X, Y, Z)
 ================
+Plot contour lines.
 
 See `~matplotlib.axes.Axes.contour`.
 """
diff --git a/galleries/plot_types/arrays/contourf.py b/galleries/plot_types/arrays/contourf.py
index bde2f984fc0f..c25afe0bfa77 100644
--- a/galleries/plot_types/arrays/contourf.py
+++ b/galleries/plot_types/arrays/contourf.py
@@ -2,6 +2,7 @@
 =================
 contourf(X, Y, Z)
 =================
+Plot filled contours.
 
 See `~matplotlib.axes.Axes.contourf`.
 """
diff --git a/galleries/plot_types/arrays/imshow.py b/galleries/plot_types/arrays/imshow.py
index be647d1f2924..c28278c6c657 100644
--- a/galleries/plot_types/arrays/imshow.py
+++ b/galleries/plot_types/arrays/imshow.py
@@ -2,6 +2,7 @@
 =========
 imshow(Z)
 =========
+Display data as an image, i.e., on a 2D regular raster.
 
 See `~matplotlib.axes.Axes.imshow`.
 """
diff --git a/galleries/plot_types/arrays/pcolormesh.py b/galleries/plot_types/arrays/pcolormesh.py
index b490dcb99d3f..4f0913f62521 100644
--- a/galleries/plot_types/arrays/pcolormesh.py
+++ b/galleries/plot_types/arrays/pcolormesh.py
@@ -2,6 +2,7 @@
 ===================
 pcolormesh(X, Y, Z)
 ===================
+Create a pseudocolor plot with a non-regular rectangular grid.
 
 `~.axes.Axes.pcolormesh` is more flexible than `~.axes.Axes.imshow` in that
 the x and y vectors need not be equally spaced (indeed they can be skewed).
diff --git a/galleries/plot_types/arrays/quiver.py b/galleries/plot_types/arrays/quiver.py
index 5d6dc808c518..4b1cbd03759c 100644
--- a/galleries/plot_types/arrays/quiver.py
+++ b/galleries/plot_types/arrays/quiver.py
@@ -2,6 +2,7 @@
 ==================
 quiver(X, Y, U, V)
 ==================
+Plot a 2D field of arrows.
 
 See `~matplotlib.axes.Axes.quiver`.
 """
diff --git a/galleries/plot_types/arrays/streamplot.py b/galleries/plot_types/arrays/streamplot.py
index 3f1e2ef4e1cc..670773d2cfd3 100644
--- a/galleries/plot_types/arrays/streamplot.py
+++ b/galleries/plot_types/arrays/streamplot.py
@@ -2,6 +2,7 @@
 ======================
 streamplot(X, Y, U, V)
 ======================
+Draw streamlines of a vector flow.
 
 See `~matplotlib.axes.Axes.streamplot`.
 """
diff --git a/galleries/plot_types/basic/fill_between.py b/galleries/plot_types/basic/fill_between.py
index a454c3c30772..feca3c658d3e 100644
--- a/galleries/plot_types/basic/fill_between.py
+++ b/galleries/plot_types/basic/fill_between.py
@@ -2,6 +2,7 @@
 =======================
 fill_between(x, y1, y2)
 =======================
+Fill the area between two horizontal curves.
 
 See `~matplotlib.axes.Axes.fill_between`.
 """
diff --git a/galleries/plot_types/basic/plot.py b/galleries/plot_types/basic/plot.py
index e494fdf24918..34cf500599bb 100644
--- a/galleries/plot_types/basic/plot.py
+++ b/galleries/plot_types/basic/plot.py
@@ -2,6 +2,7 @@
 ==========
 plot(x, y)
 ==========
+Plot y versus x as lines and/or markers.
 
 See `~matplotlib.axes.Axes.plot`.
 """
diff --git a/galleries/plot_types/basic/scatter_plot.py b/galleries/plot_types/basic/scatter_plot.py
index 792016c0e79c..07fa943b724f 100644
--- a/galleries/plot_types/basic/scatter_plot.py
+++ b/galleries/plot_types/basic/scatter_plot.py
@@ -2,6 +2,7 @@
 =============
 scatter(x, y)
 =============
+A scatter plot of y vs. x with varying marker size and/or color.
 
 See `~matplotlib.axes.Axes.scatter`.
 """
diff --git a/galleries/plot_types/basic/stackplot.py b/galleries/plot_types/basic/stackplot.py
index 5b23b52775b3..275fa5cb67ba 100644
--- a/galleries/plot_types/basic/stackplot.py
+++ b/galleries/plot_types/basic/stackplot.py
@@ -2,6 +2,8 @@
 ===============
 stackplot(x, y)
 ===============
+Draw a stacked area plot or a streamgraph.
+
 See `~matplotlib.axes.Axes.stackplot`
 """
 import matplotlib.pyplot as plt
diff --git a/galleries/plot_types/basic/stairs.py b/galleries/plot_types/basic/stairs.py
index de5761e3a7a5..df0e91d1041b 100644
--- a/galleries/plot_types/basic/stairs.py
+++ b/galleries/plot_types/basic/stairs.py
@@ -2,6 +2,7 @@
 ==============
 stairs(values)
 ==============
+A stepwise constant function as a line with bounding edges 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
diff --git a/galleries/plot_types/basic/stem.py b/galleries/plot_types/basic/stem.py
index a606482ecf9b..afd10ca1c9df 100644
--- a/galleries/plot_types/basic/stem.py
+++ b/galleries/plot_types/basic/stem.py
@@ -2,6 +2,7 @@
 ==========
 stem(x, y)
 ==========
+Create a stem plot.
 
 See `~matplotlib.axes.Axes.stem`.
 """
diff --git a/galleries/plot_types/stats/boxplot_plot.py b/galleries/plot_types/stats/boxplot_plot.py
index cdad3c52320f..996b97a2aef4 100644
--- a/galleries/plot_types/stats/boxplot_plot.py
+++ b/galleries/plot_types/stats/boxplot_plot.py
@@ -2,6 +2,7 @@
 ==========
 boxplot(X)
 ==========
+Draw a box and whisker plot.
 
 See `~matplotlib.axes.Axes.boxplot`.
 """
diff --git a/galleries/plot_types/stats/ecdf.py b/galleries/plot_types/stats/ecdf.py
index bd5f9fa9e5b2..1a8566b3d2eb 100644
--- a/galleries/plot_types/stats/ecdf.py
+++ b/galleries/plot_types/stats/ecdf.py
@@ -2,6 +2,7 @@
 =======
 ecdf(x)
 =======
+Compute and plot the empirical cumulative distribution function of x.
 
 See `~matplotlib.axes.Axes.ecdf`.
 """
diff --git a/galleries/plot_types/stats/errorbar_plot.py b/galleries/plot_types/stats/errorbar_plot.py
index 0e226e11b315..c96a08e111c1 100644
--- a/galleries/plot_types/stats/errorbar_plot.py
+++ b/galleries/plot_types/stats/errorbar_plot.py
@@ -2,6 +2,7 @@
 ==========================
 errorbar(x, y, yerr, xerr)
 ==========================
+Plot y versus x as lines and/or markers with attached errorbars.
 
 See `~matplotlib.axes.Axes.errorbar`.
 """
diff --git a/galleries/plot_types/stats/eventplot.py b/galleries/plot_types/stats/eventplot.py
index da8c33c28425..babdbe6d1ca1 100644
--- a/galleries/plot_types/stats/eventplot.py
+++ b/galleries/plot_types/stats/eventplot.py
@@ -2,6 +2,7 @@
 ============
 eventplot(D)
 ============
+Plot identical parallel lines at the given positions.
 
 See `~matplotlib.axes.Axes.eventplot`.
 """
diff --git a/galleries/plot_types/stats/hexbin.py b/galleries/plot_types/stats/hexbin.py
index 91e771308afd..9d3a2a071346 100644
--- a/galleries/plot_types/stats/hexbin.py
+++ b/galleries/plot_types/stats/hexbin.py
@@ -2,6 +2,7 @@
 ===============
 hexbin(x, y, C)
 ===============
+Make a 2D hexagonal binning plot of points x, y.
 
 See `~matplotlib.axes.Axes.hexbin`.
 """
diff --git a/galleries/plot_types/stats/hist2d.py b/galleries/plot_types/stats/hist2d.py
index 3e43f7ee8ace..d95b67539b33 100644
--- a/galleries/plot_types/stats/hist2d.py
+++ b/galleries/plot_types/stats/hist2d.py
@@ -2,6 +2,7 @@
 ============
 hist2d(x, y)
 ============
+Make a 2D histogram plot.
 
 See `~matplotlib.axes.Axes.hist2d`.
 """
diff --git a/galleries/plot_types/stats/hist_plot.py b/galleries/plot_types/stats/hist_plot.py
index 6c86a0aca216..6328fe9d07c6 100644
--- a/galleries/plot_types/stats/hist_plot.py
+++ b/galleries/plot_types/stats/hist_plot.py
@@ -2,6 +2,7 @@
 =======
 hist(x)
 =======
+Compute and plot a histogram.
 
 See `~matplotlib.axes.Axes.hist`.
 """
diff --git a/galleries/plot_types/stats/pie.py b/galleries/plot_types/stats/pie.py
index 80484a0eb932..bd8d555f0040 100644
--- a/galleries/plot_types/stats/pie.py
+++ b/galleries/plot_types/stats/pie.py
@@ -2,6 +2,7 @@
 ======
 pie(x)
 ======
+Plot a pie chart.
 
 See `~matplotlib.axes.Axes.pie`.
 """
diff --git a/galleries/plot_types/stats/violin.py b/galleries/plot_types/stats/violin.py
index c8a987a690dd..2ea2161ad91c 100644
--- a/galleries/plot_types/stats/violin.py
+++ b/galleries/plot_types/stats/violin.py
@@ -2,6 +2,7 @@
 =============
 violinplot(D)
 =============
+Make a violin plot.
 
 See `~matplotlib.axes.Axes.violinplot`.
 """
diff --git a/galleries/plot_types/unstructured/tricontour.py b/galleries/plot_types/unstructured/tricontour.py
index 83b0a212fd83..292ff551fe36 100644
--- a/galleries/plot_types/unstructured/tricontour.py
+++ b/galleries/plot_types/unstructured/tricontour.py
@@ -2,6 +2,7 @@
 ===================
 tricontour(x, y, z)
 ===================
+Draw contour lines on an unstructured triangular grid.
 
 See `~matplotlib.axes.Axes.tricontour`.
 """
diff --git a/galleries/plot_types/unstructured/tricontourf.py b/galleries/plot_types/unstructured/tricontourf.py
index da909c02f0b2..aab748e73024 100644
--- a/galleries/plot_types/unstructured/tricontourf.py
+++ b/galleries/plot_types/unstructured/tricontourf.py
@@ -2,6 +2,7 @@
 ====================
 tricontourf(x, y, z)
 ====================
+Draw contour regions on an unstructured triangular grid.
 
 See `~matplotlib.axes.Axes.tricontourf`.
 """
diff --git a/galleries/plot_types/unstructured/tripcolor.py b/galleries/plot_types/unstructured/tripcolor.py
index e2619a68444e..398877653db8 100644
--- a/galleries/plot_types/unstructured/tripcolor.py
+++ b/galleries/plot_types/unstructured/tripcolor.py
@@ -2,6 +2,7 @@
 ==================
 tripcolor(x, y, z)
 ==================
+Create a pseudocolor plot of an unstructured triangular grid.
 
 See `~matplotlib.axes.Axes.tripcolor`.
 """
diff --git a/galleries/plot_types/unstructured/triplot.py b/galleries/plot_types/unstructured/triplot.py
index 78cf8e32a318..d726c46e1e47 100644
--- a/galleries/plot_types/unstructured/triplot.py
+++ b/galleries/plot_types/unstructured/triplot.py
@@ -2,6 +2,7 @@
 =============
 triplot(x, y)
 =============
+Draw an unstructured triangular grid as lines and/or markers.
 
 See `~matplotlib.axes.Axes.triplot`.
 """
diff --git a/lib/matplotlib/quiver.py b/lib/matplotlib/quiver.py
index db4ef35f3034..8fa1962d6321 100644
--- a/lib/matplotlib/quiver.py
+++ b/lib/matplotlib/quiver.py
@@ -727,7 +727,7 @@ def _h_arrows(self, length):
 
 
 _barbs_doc = r"""
-Plot a 2D field of barbs.
+Plot a 2D field of wind barbs.
 
 Call signature::
 
diff --git a/lib/matplotlib/stackplot.py b/lib/matplotlib/stackplot.py
index 0d9b896f6f4c..dd579bcd5877 100644
--- a/lib/matplotlib/stackplot.py
+++ b/lib/matplotlib/stackplot.py
@@ -19,7 +19,7 @@ def stackplot(axes, x, *args,
               labels=(), colors=None, hatch=None, baseline='zero',
               **kwargs):
     """
-    Draw a stacked area plot.
+    Draw a stacked area plot or a streamgraph.
 
     Parameters
     ----------

From 6e244180b336dc1337ea718cefd140b6f5b23ea7 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Tue, 19 Mar 2024 23:48:54 +0100
Subject: [PATCH 2/2] DOC: Improve stairs docstring

---
 galleries/plot_types/basic/stairs.py | 2 +-
 lib/matplotlib/axes/_axes.py         | 9 ++++++---
 2 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/galleries/plot_types/basic/stairs.py b/galleries/plot_types/basic/stairs.py
index df0e91d1041b..732ded998241 100644
--- a/galleries/plot_types/basic/stairs.py
+++ b/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
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
index 627dd2c36d40..8fb8e878712b 100644
--- a/lib/matplotlib/axes/_axes.py
+++ b/lib/matplotlib/axes/_axes.py
@@ -7104,8 +7104,11 @@ 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
         ----------
@@ -7113,7 +7116,7 @@ def stairs(self, values, edges=None, *,
             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'