matplotlib · timhoffm · Oct 26, 2024 · Sep 22, 2024 · Oct 25, 2024 · Oct 25, 2024
diff --git a/doc/missing-references.json b/doc/missing-references.json
@@ -308,7 +308,7 @@
       "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.fill_betweenx:121",
       "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.hexbin:217",
       "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.pcolor:186",
-      "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.quiver:215",
+      "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.quiver:255",
       "lib/matplotlib/collections.py:docstring of matplotlib.artist.AsteriskPolygonCollection.set:44",
       "lib/matplotlib/collections.py:docstring of matplotlib.artist.CircleCollection.set:44",
       "lib/matplotlib/collections.py:docstring of matplotlib.artist.PathCollection.set:44",
@@ -323,11 +323,11 @@
       "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.fill_betweenx:121",
       "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.hexbin:217",
       "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.pcolor:186",
-      "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.quiver:215",
+      "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.quiver:255",
       "lib/matplotlib/quiver.py:docstring of matplotlib.artist.Barbs.set:45",
       "lib/matplotlib/quiver.py:docstring of matplotlib.artist.Quiver.set:45",
       "lib/matplotlib/quiver.py:docstring of matplotlib.quiver.Barbs:212",
-      "lib/matplotlib/quiver.py:docstring of matplotlib.quiver.Quiver:251",
+      "lib/matplotlib/quiver.py:docstring of matplotlib.quiver.Quiver:291",
       "lib/mpl_toolkits/mplot3d/art3d.py:docstring of matplotlib.artist.Path3DCollection.set:46",
       "lib/mpl_toolkits/mplot3d/art3d.py:docstring of matplotlib.artist.Poly3DCollection.set:45"
     ],

diff --git a/lib/matplotlib/quiver.py b/lib/matplotlib/quiver.py
@@ -87,21 +87,29 @@
 angles : {'uv', 'xy'} or array-like, default: 'uv'
     Method for determining the angle of the arrows.
 
-    - 'uv': Arrow direction in screen coordinates. Use this if the arrows
-      symbolize a quantity that is not based on *X*, *Y* data coordinates.
+    - 'uv':  Arrow directions are based on
+      :ref:`display coordinates <coordinate-systems>`; i.e. a 45° angle will
+      always show up as diagonal on the screen, irrespective of figure or Axes
+      aspect ratio or Axes data ranges. This is useful when the arrows represent
+      a quantity whose direction is not tied to the x and y data coordinates.
 
       If *U* == *V* the orientation of the arrow on the plot is 45 degrees
       counter-clockwise from the horizontal axis (positive to the right).
 
     - 'xy': Arrow direction in data coordinates, i.e. the arrows point from
-      (x, y) to (x+u, y+v). Use this e.g. for plotting a gradient field.
+      (x, y) to (x+u, y+v). This is ideal for vector fields or gradient plots
+      where the arrows should directly represent movements or gradients in the
+      x and y directions.
 
     - Arbitrary angles may be specified explicitly as an array of values
       in degrees, counter-clockwise from the horizontal axis.
 
       In this case *U*, *V* is only used to determine the length of the
       arrows.
 
+      For example, ``angles=[30, 60, 90]`` will orient the arrows at 30, 60, and 90
+      degrees respectively, regardless of the *U* and *V* components.
+
     Note: inverting a data axis will correspondingly invert the
     arrows only with ``angles='xy'``.
 
@@ -114,26 +122,59 @@
 scale : float, optional
     Scales the length of the arrow inversely.
 
-    Number of data units per arrow length unit, e.g., m/s per plot width; a
-    smaller scale parameter makes the arrow longer. Default is *None*.
+    Number of data values represented by one unit of arrow length on the plot.
+    For example, if the data represents velocity in meters per second (m/s), the
+    scale parameter determines how many meters per second correspond to one unit of
+    arrow length relative to the width of the plot.
+    Smaller scale parameter makes the arrow longer.
+
+    By default, an autoscaling algorithm is used to scale the arrow length to a
+    reasonable size, which is based on the average vector length and the number of
+    vectors.
+
+    The arrow length unit is given by the *scale_units* parameter.
+
+scale_units : {'width', 'height', 'dots', 'inches', 'x', 'y', 'xy'}, default: 'width'
+
+    The physical image unit, which is used for rendering the scaled arrow data *U*, *V*.
+
+    The rendered arrow length is given by
+
+        length in x direction = $\\frac{u}{\\mathrm{scale}} \\mathrm{scale_unit}$
+
+        length in y direction = $\\frac{v}{\\mathrm{scale}} \\mathrm{scale_unit}$
+
+    For example, ``(u, v) = (0.5, 0)`` with ``scale=10, scale_unit="width"`` results
+    in a horizontal arrow with a length of *0.5 / 10 * "width"*, i.e. 0.05 times the
+    Axes width.
+
+    Supported values are:
+
+    - 'width' or 'height': The arrow length is scaled relative to the width or height
+       of the Axes.
+       For example, ``scale_units='width', scale=1.0``, will result in an arrow length
+       of width of the Axes.
 
-    If *None*, a simple autoscaling algorithm is used, based on the average
-    vector length and the number of vectors. The arrow length unit is given by
-    the *scale_units* parameter.
+    - 'dots': The arrow length of the arrows is in measured in display dots (pixels).
 
-scale_units : {'width', 'height', 'dots', 'inches', 'x', 'y', 'xy'}, optional
-    If the *scale* kwarg is *None*, the arrow length unit. Default is *None*.
+    - 'inches': Arrow lengths are scaled based on the DPI (dots per inch) of the figure.
+       This ensures that the arrows have a consistent physical size on the figure,
+       in inches, regardless of data values or plot scaling.
+       For example, ``(u, v) = (1, 0)`` with ``scale_units='inches', scale=2`` results
+       in a 0.5 inch-long arrow.
 
-    e.g. *scale_units* is 'inches', *scale* is 2.0, and ``(u, v) = (1, 0)``,
-    then the vector will be 0.5 inches long.
+    - 'x' or 'y': The arrow length is scaled relative to the x or y axis units.
+       For example, ``(u, v) = (0, 1)`` with ``scale_units='x', scale=1`` results
+       in a vertical arrow with the length of 1 x-axis unit.
 
-    If *scale_units* is 'width' or 'height', then the vector will be half the
-    width/height of the axes.
+    - 'xy': Arrow length will be same as 'x' or 'y' units.
+       This is useful for creating vectors in the x-y plane where u and v have
+       the same units as x and y. To plot vectors in the x-y plane with u and v having
+       the same units as x and y, use ``angles='xy', scale_units='xy', scale=1``.
 
-    If *scale_units* is 'x' then the vector will be 0.5 x-axis
-    units. To plot vectors in the x-y plane, with u and v having
-    the same units as x and y, use
-    ``angles='xy', scale_units='xy', scale=1``.
+    Note: Setting *scale_units* without setting scale does not have any effect because
+    the scale units only differ by a constant factor and that is rescaled through
+    autoscaling.
 
 units : {'width', 'height', 'dots', 'inches', 'x', 'y', 'xy'}, default: 'width'
     Affects the arrow size (except for the length). In particular, the shaft