DOC: Clarify that parameters to gridded data plotting functions are positional-only

timhoffm · timhoffm · commit 9fe39a72319c · 2024-04-10T22:48:56.000+02:00
Closes #28047 and the already closed #11526. This introduces the positional-only marker `/` into the call signatures (`pcolorfast` already had it). While IIRC I originally opted against adding it for simplicity, the above issues show that this is not clear enough. It's helpful for experienced people and I believe it does not distract people who don't know what it is too much because it's here always at the end before **kwargs. Additionally, it does not hurt to spell it out in text as well.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -6038,10 +6038,12 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,
 
         Call signature::
 
-            pcolor([X, Y,] C, **kwargs)
+            pcolor([X, Y,] C, /, **kwargs)
 
         *X* and *Y* can be used to specify the corners of the quadrilaterals.
 
+        The arguments *X*, *Y*, *C* are positional-only.
+
         .. hint::
 
             ``pcolor()`` can be very slow for large arrays. In most
@@ -6253,10 +6255,12 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
 
         Call signature::
 
-            pcolormesh([X, Y,] C, **kwargs)
+            pcolormesh([X, Y,] C, /, **kwargs)
 
         *X* and *Y* can be used to specify the corners of the quadrilaterals.
 
+        The arguments *X*, *Y*, *C* are positional-only.
+
         .. hint::
 
            `~.Axes.pcolormesh` is similar to `~.Axes.pcolor`. It is much faster
@@ -6480,6 +6484,8 @@ def pcolorfast(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
 
             ax.pcolorfast([X, Y], C, /, **kwargs)
 
+        The arguments *X*, *Y*, *C* are positional-only.
+
         This method is similar to `~.Axes.pcolor` and `~.Axes.pcolormesh`.
         It's designed to provide the fastest pcolor-type plotting with the
         Agg backend. To achieve this, it uses different algorithms internally
@@ -6662,7 +6668,9 @@ def contour(self, *args, **kwargs):
 
         Call signature::
 
-            contour([X, Y,] Z, [levels], **kwargs)
+            contour([X, Y,] Z, /, [levels], **kwargs)
+
+        The arguments *X*, *Y*, *Z* are positional-only.
         %(contour_doc)s
         """
         kwargs['filled'] = False
@@ -6678,7 +6686,9 @@ def contourf(self, *args, **kwargs):
 
         Call signature::
 
-            contourf([X, Y,] Z, [levels], **kwargs)
+            contourf([X, Y,] Z, /, [levels], **kwargs)
+
+        The arguments *X*, *Y*, *Z* are positional-only.
         %(contour_doc)s
         """
         kwargs['filled'] = True
diff --git a/lib/matplotlib/quiver.py b/lib/matplotlib/quiver.py
@@ -32,10 +32,11 @@
 
 Call signature::
 
-  quiver([X, Y], U, V, [C], **kwargs)
+  quiver([X, Y], U, V, [C], /, **kwargs)
 
 *X*, *Y* define the arrow locations, *U*, *V* define the arrow directions, and
-*C* optionally sets the color.
+*C* optionally sets the color. The arguments *X*, *Y*, *U*, *V*, *C* are
+positional-only.
 
 **Arrow length**
 
@@ -731,13 +732,14 @@ def _h_arrows(self, length):
 
 Call signature::
 
-  barbs([X, Y], U, V, [C], **kwargs)
+  barbs([X, Y], U, V, [C], /, **kwargs)
 
 Where *X*, *Y* define the barb locations, *U*, *V* define the barb
 directions, and *C* optionally sets the color.
 
-All arguments may be 1D or 2D. *U*, *V*, *C* may be masked arrays, but masked
-*X*, *Y* are not supported at present.
+The arguments *X*, *Y*, *U*, *V*, *C* are positional-only and may be
+1D or 2D. *U*, *V*, *C* may be masked arrays, but masked *X*, *Y*
+are not supported at present.
 
 Barbs are traditionally used in meteorology as a way to plot the speed
 and direction of wind observations, but can technically be used to
