DOC: scales - built in options and custom usefulness

rcomer · rcomer · commit 97390e3b04d8 · 2025-01-05T14:16:58.000Z
diff --git a/galleries/examples/scales/custom_scale.py b/galleries/examples/scales/custom_scale.py
@@ -6,12 +6,21 @@
 ============
 
 Create a custom scale, by implementing the scaling use for latitude data in a
-Mercator Projection.
+Mercator Projection.  A custom scale is useful when
 
-Unless you are making special use of the `.Transform` class, you probably
-don't need to use this verbose method, and instead can use `~.scale.FuncScale`
-and the ``'function'`` option of `~.Axes.set_xscale` and `~.Axes.set_yscale`.
-See the last example in :doc:`/gallery/scales/scales`.
+* You are making special use of the `.Transform` class, such as the special
+  handling of values beyond the threshold in ``MercatorLatitudeTransform``
+  below.
+
+* You want to override the default locators and formatters for the axis
+  (``set_default_locators_and_formatters`` below).
+
+* You want to limit the range of the the axis (``limit_range_for_scale`` below).
+
+If you do not need any of the above, then you probably don't need to use this
+verbose method, and instead can use `~.scale.FuncScale` and the ``'function'``
+option of `~.Axes.set_xscale` and `~.Axes.set_yscale`. See the last example in
+:doc:`/gallery/scales/scales`.
 """
 
 import numpy as np
diff --git a/lib/matplotlib/axis.py b/lib/matplotlib/axis.py
@@ -759,26 +759,22 @@ def _set_axes_scale(self, value, **kwargs):
 
         Parameters
         ----------
-        value : {"linear", "log", "symlog", "logit", ...} or `.ScaleBase`
-            The axis scale type to apply.
+        value : str or `.ScaleBase`
+            The axis scale type to apply.  Supported string values are "linear", "log",
+            "symlog", "logit", "function", "functionlog", "asinh", and the names of any
+            custom scales registered using `matplotlib.scale.register_scale`.
 
         **kwargs
-            Different keyword arguments are accepted, depending on the scale.
-            See the respective class keyword arguments:
+            If *value* is a string, keywords are passed to the instantiation method of
+            the respective class:
 
             - `matplotlib.scale.LinearScale`
             - `matplotlib.scale.LogScale`
             - `matplotlib.scale.SymmetricalLogScale`
             - `matplotlib.scale.LogitScale`
             - `matplotlib.scale.FuncScale`
+            - `matplotlib.scale.FuncScaleLog`
             - `matplotlib.scale.AsinhScale`
-
-        Notes
-        -----
-        By default, Matplotlib supports the above-mentioned scales.
-        Additionally, custom scales may be registered using
-        `matplotlib.scale.register_scale`. These scales can then also
-        be used here.
         """
         name = self._get_axis_name()
         old_default_lims = (self.get_major_locator()
