Improvements to docstring and to API docs.

efiring · efiring · commit 3eb471dadd2f · 2020-05-04T20:26:51.000-10:00
diff --git a/doc/api/axis_api.rst b/doc/api/axis_api.rst
@@ -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
 
 
 
diff --git a/lib/matplotlib/axis.py b/lib/matplotlib/axis.py
@@ -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
