From 49585f97bef2d004d96bc8ad2574ac2dbe3421a6 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Fri, 2 Nov 2018 22:11:13 +0100
Subject: [PATCH] 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 ceabef35f356..6b89e26c8dcb 100644
--- a/lib/matplotlib/axes/_base.py
+++ b/lib/matplotlib/axes/_base.py
@@ -3248,9 +3248,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):
         """
@@ -3259,22 +3264,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):
@@ -3630,9 +3637,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):
         """
@@ -3641,22 +3653,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):