DOC: Document kwargs scope for tick setter functions

To clarify expectations c.f. matplotlib#23272 (comment)
timhoffm · Jun 25, 2024 · 1fa0eb7 · 1fa0eb7
1 parent 8b9cb14
commit 1fa0eb7
Show file tree

Hide file tree

Showing 2 changed files with 45 additions and 2 deletions.
diff --git a/lib/matplotlib/axis.py b/lib/matplotlib/axis.py
@@ -2028,7 +2028,9 @@ def set_ticklabels(self, labels, *, minor=False, fontdict=None, **kwargs):
 
             .. warning::
 
-                This only sets the properties of the current ticks.
+                This only sets the properties of the current ticks, which is
+                only sufficient for static plots.
+
                 Ticks are not guaranteed to be persistent. Various operations
                 can create, delete and modify the Tick instances. There is an
                 imminent risk that these settings can get lost if you work on
@@ -2154,7 +2156,21 @@ def set_ticks(self, ticks, labels=None, *, minor=False, **kwargs):
 
         **kwargs
             `.Text` properties for the labels. Using these is only allowed if
-            you pass *labels*. In other cases, please use `~.Axes.tick_params`.
+            you pass *labels*. In other cases, please use `.Axis.tick_params`.
+
+            .. warning::
+
+                This only sets the properties of the current ticks, which is
+                only sufficient for static plots.
+
+                Ticks are not guaranteed to be persistent. Various operations
+                can create, delete and modify the Tick instances. There is an
+                imminent risk that these settings can get lost if you work on
+                the figure further (including also panning/zooming on a
+                displayed figure).
+
+                Use `.Axis.tick_params` instead if possible.
+
 
         Notes
         -----

diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -2182,6 +2182,20 @@ def xticks(
     **kwargs
         `.Text` properties can be used to control the appearance of the labels.
 
+        .. warning::
+
+            This only sets the properties of the current ticks, which is
+            only sufficient for static plots.
+
+            Ticks are not guaranteed to be persistent. Various operations
+            can create, delete and modify the Tick instances. There is an
+            imminent risk that these settings can get lost if you work on
+            the figure further (including also panning/zooming on a
+            displayed figure).
+
+            Use `~.pyplot.tick_params` instead if possible.
+
+
     Returns
     -------
     locs
@@ -2253,6 +2267,19 @@ def yticks(
     **kwargs
         `.Text` properties can be used to control the appearance of the labels.
 
+        .. warning::
+
+            This only sets the properties of the current ticks, which is
+            sufficient for static plots.
+
+            Ticks are not guaranteed to be persistent. Various operations
+            can create, delete and modify the Tick instances. There is an
+            imminent risk that these settings can get lost if you work on
+            the figure further (including also panning/zooming on a
+            displayed figure).
+
+            Use `~.pyplot.tick_params` instead if possible.
+
     Returns
     -------
     locs