matplotlib
diff --git a/‎doc/api/axis_api.rst
Copy file name to clipboardExpand all lines: doc/api/axis_api.rst
+7-4Lines changed: 7 additions & 4 deletions b/‎doc/api/axis_api.rst
Copy file name to clipboardExpand all lines: doc/api/axis_api.rst
+7-4Lines changed: 7 additions & 4 deletions
diff --git a/‎lib/matplotlib/axis.py
Copy file name to clipboardExpand all lines: lib/matplotlib/axis.py
+3-2Lines changed: 3 additions & 2 deletions b/‎lib/matplotlib/axis.py
Copy file name to clipboardExpand all lines: lib/matplotlib/axis.py
+3-2Lines changed: 3 additions & 2 deletions
@@ -226,17 +226,20 @@ Other
 Discouraged
 -----------
 
-These methods implicitly use `~matplotlib.ticker.FixedLocator` and
-`~matplotlib.ticker.FixedFormatter`.  They can be convenient, but if
-not used together may de-couple your tick labels from your data.
+These methods should be used together with care, calling ``set_ticks``
+to specify the desired tick locations **before** calling ``set_ticklabels`` to
+specify a matching series of labels.  Calling ``set_ticks`` makes a
+`~matplotlib.ticker.FixedLocator`; it's list of locations is then used by
+``set_ticklabels`` to make an appropriate
+`~matplotlib.ticker.FuncFormatter`.
 
 .. autosummary::
    :toctree: _as_gen
    :template: autosummary.rst
    :nosignatures:
 
-   Axis.set_ticklabels
    Axis.set_ticks
+   Axis.set_ticklabels
 
 
 
 
@@ -1617,8 +1617,9 @@ def set_ticklabels(self, ticklabels, *, minor=False, **kwargs):
         Parameters
         ----------
         ticklabels : sequence of str or of `.Text`\s
-            List of texts for tick labels; must include values for non-visible
-            labels.
+            Texts for labeling each tick location in the sequence set by
+            `.Axis.set_ticks`; the number of labels must match the number of
+            locations.
         minor : bool
             If True, set minor ticks instead of major ticks.
         **kwargs