From 43b6cdea34ead25b6067be008281d473abfb96db Mon Sep 17 00:00:00 2001
From: Thomas A Caswell <tcaswell@gmail.com>
Date: Sat, 3 Nov 2018 11:37:39 -0400
Subject: [PATCH] Backport PR #12720: Improve docs on Axes scales

---
 lib/matplotlib/axes/_base.py | 70 +++++++++++++++++++++---------------
 1 file changed, 42 insertions(+), 28 deletions(-)

diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
index 42ea8055d9cd..079e2723686f 100644
--- a/lib/matplotlib/axes/_base.py
+++ b/lib/matplotlib/axes/_base.py
@@ -3270,9 +3270,14 @@ def set_xlim(self, left=None, right=None, emit=True, auto=False,
         return left, right
 
     def get_xscale(self):
+        """
+        Return the x-axis scale as string.
+
+        See Also
+        --------
+        set_xscale
+        """
         return self.xaxis.get_scale()
-    get_xscale.__doc__ = "Return the xaxis scale string: %s""" % (
-        ", ".join(mscale.get_scale_names()))
 
     def set_xscale(self, value, **kwargs):
         """
@@ -3281,22 +3286,24 @@ def set_xscale(self, value, **kwargs):
         Parameters
         ----------
         value : {"linear", "log", "symlog", "logit", ...}
-            scaling strategy to apply
+            The axis scale type to apply.
 
-        Notes
-        -----
-        Different kwargs are accepted, depending on the scale. See
-        the `~matplotlib.scale` module for more information.
-
-        See also
-        --------
-        matplotlib.scale.LinearScale : linear transform
+        **kwargs
+            Different keyword arguments are accepted, depending on the scale.
+            See the respective class keyword arguments:
 
-        matplotlib.scale.LogTransform : log transform
+            - `matplotlib.scale.LinearScale`
+            - `matplotlib.scale.LogScale`
+            - `matplotlib.scale.SymmetricalLogScale`
+            - `matplotlib.scale.LogitScale`
 
-        matplotlib.scale.SymmetricalLogTransform : symlog transform
 
-        matplotlib.scale.LogisticTransform : logit transform
+        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.
         """
         g = self.get_shared_x_axes()
         for ax in g.get_siblings(self):
@@ -3653,9 +3660,14 @@ def set_ylim(self, bottom=None, top=None, emit=True, auto=False,
         return bottom, top
 
     def get_yscale(self):
+        """
+        Return the x-axis scale as string.
+
+        See Also
+        --------
+        set_yscale
+        """
         return self.yaxis.get_scale()
-    get_yscale.__doc__ = "Return the yaxis scale string: %s""" % (
-        ", ".join(mscale.get_scale_names()))
 
     def set_yscale(self, value, **kwargs):
         """
@@ -3664,22 +3676,24 @@ def set_yscale(self, value, **kwargs):
         Parameters
         ----------
         value : {"linear", "log", "symlog", "logit", ...}
-            scaling strategy to apply
+            The axis scale type to apply.
 
-        Notes
-        -----
-        Different kwargs are accepted, depending on the scale. See
-        the `~matplotlib.scale` module for more information.
-
-        See also
-        --------
-        matplotlib.scale.LinearScale : linear transform
+        **kwargs
+            Different keyword arguments are accepted, depending on the scale.
+            See the respective class keyword arguments:
 
-        matplotlib.scale.LogTransform : log transform
+            - `matplotlib.scale.LinearScale`
+            - `matplotlib.scale.LogScale`
+            - `matplotlib.scale.SymmetricalLogScale`
+            - `matplotlib.scale.LogitScale`
 
-        matplotlib.scale.SymmetricalLogTransform : symlog transform
 
-        matplotlib.scale.LogisticTransform : logit transform
+        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.
         """
         g = self.get_shared_y_axes()
         for ax in g.get_siblings(self):