ticker.{Eng,Scalar}Formatter: address review comments

doronbehar · doronbehar · commit e7176829bab4 · 2024-07-03T22:54:18.000+03:00
diff --git a/doc/users/next_whats_new/EngFormatter-offset.rst b/doc/users/next_whats_new/EngFormatter-offset.rst
@@ -2,8 +2,25 @@ ticker.EngFormatter now computes offset by default
 --------------------------------------------------
 
 ``ticker.EngFormatter`` was modified to act very similar to
-``ticker.ScalarFormatter``, such that it computes the best offset of the axis
-data, and shows the offset with the known SI quantity prefixes. To disable this
-new behavior, simply pass ``useOffset=False`` when you instantiate it. If offsets
-are disabled, or if there is no particular offset that fits your axis data, the
-formatter will revert to the old behavior.
+``ticker.ScalarFormatter``, such that it is capable of computing the best
+offset of the axis data, and show the offset with the known SI quantity
+prefixes.
+
+Since this is a change in behavior, this behavior is disabled by default (in
+contrast to the default behavior of ``ScalarFormatter``. To enable it, pass
+``useOffset=True`` when you instantiate ``EngFormatter``.
+
+Here's an example result:
+
+.. plot::
+
+    import matplotlib.pyplot as plt
+    import matplotlib.ticker as mticker
+
+    fig, ax = plt.subplots()
+    offset = int(1e7)
+    ydata = range(offset, offset+5)
+    ax.plot(ydata)
+    ax.set_yticks(ydata)
+    ax.yaxis.set_major_formatter(mticker.EngFormatter(useOffset=True, unit="Hz"))
+    plt.show()
diff --git a/lib/matplotlib/ticker.py b/lib/matplotlib/ticker.py
@@ -411,6 +411,8 @@ class ScalarFormatter(Formatter):
         To enable/disable the use of TeX's math mode for rendering the
         numbers in the formatter.
 
+        .. versionadded:: 3.10
+
     Notes
     -----
     In addition to the parameters above, the formatting of scientific vs.
@@ -1370,7 +1372,7 @@ class EngFormatter(ScalarFormatter):
     }
 
     def __init__(self, unit="", places=None, sep=" ", *, usetex=None,
-                 useMathText=None, useOffset=None):
+                 useMathText=None, useOffset=False):
         r"""
         Parameters
         ----------
@@ -1404,8 +1406,12 @@ def __init__(self, unit="", places=None, sep=" ", *, usetex=None,
         useMathText : bool, default: :rc:`axes.formatter.use_mathtext`
             To enable/disable the use mathtext for rendering the numbers in
             the formatter.
-        useOffset : bool or float, default: :rc:`axes.formatter.useoffset`
+        useOffset : bool or float, default: False
             Whether to use offset notation. See `.set_useOffset`.
+            Passing None will make it default to the value of
+            :rc:`axes.formatter.useoffset`
+
+            .. versionadded:: 3.10
         """
         self.unit = unit
         self.places = places
