From a48cf02523ea9653165f1f850a3f3287f758bb1f Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Tue, 25 Jun 2024 21:57:27 +0200
Subject: [PATCH] DOC: Document kwargs scope for tick setter functions

To clarify expectations c.f. https://github.com/matplotlib/matplotlib/issues/23272#issuecomment-2189516852
---
 lib/matplotlib/axis.py   |  4 +++-
 lib/matplotlib/pyplot.py | 29 +++++++++++++++++++++++++++++
 2 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/lib/matplotlib/axis.py b/lib/matplotlib/axis.py
index 921de9271be8..1eb1b2331db3 100644
--- 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
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
index 9b516d5aae8a..7dcd83565d52 100644
--- a/lib/matplotlib/pyplot.py
+++ b/lib/matplotlib/pyplot.py
@@ -2182,6 +2182,21 @@ 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 if you either pass *ticks*, resulting in a
+            fixed list of ticks, or if the plot is static.
+
+            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 +2268,20 @@ 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
+            only sufficient if you either pass *ticks*, resulting in a
+            fixed list of ticks, or if the plot is static.
+
+            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