improve docstrings of pyplot.xscale and pyplot.yscale

timhoffm · timhoffm · commit d4b968bcd346 · 2018-02-13T23:51:39.000+01:00
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -1602,13 +1602,23 @@ def ylim(*args, **kwargs):
 @docstring.dedent_interpd
 def xscale(*args, **kwargs):
     """
-    Set the scaling of the *x*-axis.
+    Set the scaling of the x-axis.
 
-    call signature::
+    Call signature::
 
-      xscale(scale, **kwargs)
+        xscale(scale, **kwargs)
+
+    Parameters
+    ----------
+    scale : [%(scale)s]
+        The scaling type.
+    **kwargs
+        Additional parameters depend on *scale*. See Notes.
 
-    The available scales are: %(scale)s
+    Notes
+    -----
+    This is the pyplot equivalent of calling `~.Axes.set_xscale` on the
+    current axes.
 
     Different keywords may be accepted, depending on the scale:
 
@@ -1620,13 +1630,23 @@ def xscale(*args, **kwargs):
 @docstring.dedent_interpd
 def yscale(*args, **kwargs):
     """
-    Set the scaling of the *y*-axis.
+    Set the scaling of the y-axis.
 
-    call signature::
+    Call signature::
 
-      yscale(scale, **kwargs)
+        yscale(scale, **kwargs)
+
+    Parameters
+    ----------
+    scale : [%(scale)s]
+        The scaling type.
+    **kwargs
+        Additional parameters depend on *scale*. See Notes.
 
-    The available scales are: %(scale)s
+    Notes
+    -----
+    This is the pyplot equivalent of calling `~.Axes.set_yscale` on the
+    current axes.
 
     Different keywords may be accepted, depending on the scale:
 
