Merge pull request matplotlib#27497 from anntzer/ab

Clarify that set_axisbelow doesn't move grids below images.

Author: timhoffm

lib/matplotlib/axes/_base.py

@@ -3157,13 +3157,18 @@ def set_axisbelow(self, b):
         b : bool or 'line'
             Possible values:
 
-            - *True* (zorder = 0.5): Ticks and gridlines are below all Artists.
+            - *True* (zorder = 0.5): Ticks and gridlines are below patches and
+              lines, though still above images.
             - 'line' (zorder = 1.5): Ticks and gridlines are above patches
               (e.g. rectangles, with default zorder = 1) but still below lines
               and markers (with their default zorder = 2).
             - *False* (zorder = 2.5): Ticks and gridlines are above patches
               and lines / markers.
 
+        Notes
+        -----
+        For more control, call the `~.Artist.set_zorder` method of each axis.
+
         See Also
         --------
         get_axisbelow