Merge pull request matplotlib#31414 from timhoffm/doc-formatter

jklymak · web-flow · commit 6871eccaaf1a · 2026-03-28T15:14:17.000-07:00
DOC: Improve Formatter documentation
diff --git a/doc/api/ticker_api.rst b/doc/api/ticker_api.rst
@@ -5,6 +5,7 @@
 .. automodule:: matplotlib.ticker
    :members:
    :undoc-members:
+   :special-members: __call__
    :show-inheritance:
 
 
diff --git a/lib/matplotlib/ticker.py b/lib/matplotlib/ticker.py
@@ -199,41 +199,84 @@ def create_dummy_axis(self, **kwargs):
 class Formatter(TickHelper):
     """
     Create a string based on a tick value and location.
+
+    The Formatter provides four formatting methods for different use cases:
+
+    - `format_ticks`: The public API for generating tick labels from a set of
+      tick values.
+    - `__call__`: The low-level primitive for formatting a single tick value,
+      potentially in the context of multiple values.
+    - `format_data`: Context-independent representation of a single value.
+      Used internally, e.g. for offset and scientific-notation strings.
+    - `format_data_short`: Concise plain-text representation of a single value
+      for the interactive mouseover tooltip.
     """
     # some classes want to see all the locs to help format
     # individual ones
     locs = []
 
     def __call__(self, x, pos=None):
         """
-        Return the format for tick value *x* at index *pos*.
-        ``pos=None`` indicates an unspecified location.
+        Return the tick label strings for value *x* at tick index *pos*.
+
+        This is the low-level formatting primitive for a single tick in
+        the context of multiple ticks. Any context-dependent state
+        (e.g. locs, offset, order of magnitude) must already be configured,
+        typically by a prior call to ``format_ticks`` or ``set_locs``.
+
+        *pos* defines the index into ``self.locs`` so that the format can
+        depend on the location. ``pos=None`` indicates an unspecified
+        location.
+
+        The output may contain mathtext or LaTeX markup.
+
+        Subclasses must override this method.
         """
         raise NotImplementedError('Derived must override')
 
     def format_ticks(self, values):
         """
-        Return the tick labels strings for all *values*.
+        Return the tick label strings for all *values*.
 
-        This method is the public API to generate a meaningful format for a set
-        of values, e.g. by ensuring an appropriate precision.
+        This is the public API for generating tick labels.  It calls
+        ``set_locs`` to configure context-dependent formatting state before
+        delegating to ``__call__`` for each individual value.
+
+        The output may contain mathtext or LaTeX markup.
+
+        Use this method (rather than ``__call__``) whenever formatting a
+        complete set of tick values, so that formatters which need to see
+        all tick locations (e.g. to determine precision, offsets, or which
+        date components to display) can work correctly.
         """
         self.set_locs(values)
         return [self(value, i) for i, value in enumerate(values)]
 
     def format_data(self, value):
         """
-        Return the full string representation of the value with the
-        position unspecified.
+        Return the context-independent string representation of a single *value*.
+
+        This is used internally, e.g. for constructing offset and
+        scientific-notation strings.  It always formats with ``pos=None``
+        and should return a context-independent representation
+        rather than a concise tick label.
+
+        The output may contain mathtext or LaTeX markup.
         """
         return self.__call__(value)
 
     def format_data_short(self, value):
         """
-        Return the mouseover-text representation of a value.
+        Return a short string representation of *value* for the mouseover
+        tooltip (the coordinate display in the interactive figure window).
+
+        This should return concise, plain text (no mathtext / LaTeX).
+        The precision is typically adapted to the current axis resolution
+        so that neighbouring pixels produce distinguishable labels.
 
-        This defaults to the representation returned by `.Formatter.format_data`,
-        but subclasses may override this.
+        Defaults to `.Formatter.format_data`; subclasses should override
+        this to provide a plain-text representation that is independent
+        of the current tick locations.
 
         Note: The mouseover text can be customized by setting the
         ``Axes.fmt_xdata`` and ``Axes.fmt_ydata`` attributes.
