@@ -2701,8 +2701,9 @@ def set_axisbelow(self, b):
27012701 Possible values:
27022702
27032703 - *True* (zorder = 0.5): Ticks and gridlines are below all Artists.
2704- - 'line' (zorder = 1.5): Ticks and gridlines are above patches (
2705- e.g. rectangles) but still below lines / markers.
2704+ - 'line' (zorder = 1.5): Ticks and gridlines are above patches
2705+ (e.g. rectangles, with default zorder = 1) but still below lines
2706+ and markers (with their default zorder = 2).
27062707 - *False* (zorder = 2.5): Ticks and gridlines are above patches
27072708 and lines / markers.
27082709
@@ -2730,17 +2731,17 @@ def grid(self, b=None, which='major', axis='both', **kwargs):
27302731
27312732 Parameters
27322733 ----------
2733- b : bool or None
2734+ b : bool or None, optional
27342735 Whether to show the grid lines. If any *kwargs* are supplied,
27352736 it is assumed you want the grid on and *b* will be set to True.
27362737
27372738 If *b* is *None* and there are no *kwargs*, this toggles the
27382739 visibility of the lines.
27392740
2740- which : {'major', 'minor', 'both'}
2741+ which : {'major', 'minor', 'both'}, optional
27412742 The grid lines to apply the changes on.
27422743
2743- axis : {'both', 'x', 'y'}
2744+ axis : {'both', 'x', 'y'}, optional
27442745 The axis to apply the changes on.
27452746
27462747 **kwargs : `.Line2D` properties
@@ -2754,7 +2755,11 @@ def grid(self, b=None, which='major', axis='both', **kwargs):
27542755
27552756 Notes
27562757 -----
2757- The grid will be drawn according to the axes' zorder and not its own.
2758+ The axis is drawn as a unit, so the effective zorder for drawing the
2759+ grid is determined by the zorder of each axis, not by the zorder of the
2760+ `.Line2D` objects comprising the grid. Therefore, to set grid zorder,
2761+ use `.set_axisbelow` or, for more control, call the
2762+ `~matplotlib.axis.Axis.set_zorder` method of each axis.
27582763 """
27592764 if len (kwargs ):
27602765 b = True
0 commit comments