improved documentation of quvier plot

Kaustbh · Kaustbh · commit d902ee3a9d75 · 2024-09-27T23:58:45.000+05:30
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,23 +122,27 @@
 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 units per 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. Default is *None*.
 
     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.
 
 scale_units : {'width', 'height', 'dots', 'inches', 'x', 'y', 'xy'}, optional
-    If the *scale* kwarg is *None*, the arrow length unit. Default is *None*.
+    If the *scale* kwarg is *None*, the arrow length unit is automatically chosen based
+    on scale_units. Default is *None*.
 
     e.g. *scale_units* is 'inches', *scale* is 2.0, and ``(u, v) = (1, 0)``,
     then the vector will be 0.5 inches long.
 
-    If *scale_units* is 'width' or 'height', then the vector will be half the
-    width/height of the axes.
+    If *scale_units* is 'width' or 'height', and *scale* is 2.0, then the vector will
+    be half the width/height of the axes.
 
-    If *scale_units* is 'x' then the vector will be 0.5 x-axis
+    If *scale_units* is 'x', and *scale* is 2.0, 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``.
