improve docstrings of pyplot.xticks and pyplot.yticks

timhoffm · timhoffm · commit b6cccde11ec0 · 2018-01-22T00:11:29.000+01:00
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -1632,24 +1632,60 @@ def yscale(*args, **kwargs):
 
 def xticks(*args, **kwargs):
     """
-    Get or set the *x*-limits of the current tick locations and labels.
+    Get or set the current tick locations and labels of the x-axis.
 
-    ::
+    Call signatures::
+
+        locs, labels = xticks()           # Get locations and labels
+
+        xticks(locs, [labels], **kwargs)  # Set locations and labels
+
+    Parameters
+    ----------
+    locs : array_like
+        A list of positions at which ticks should be placed.
+
+    labels : array_like, optional
+        A list of explicit labels to place the the given *locs*. You can pass
+        an empty list to disable xticks.
+
+    **kwargs
+        :class:`.Text` properties can be used to control the appearence of
+        the labels.
+
+    Returns
+    -------
+    locs
+        An array of label locations.
+    labels
+        A list of `.Text` objects.
+
+    Notes
+    -----
+    This is just a convenient shortcut for calling `.get_xticks` and
+    `.get_xticklabels` or `.set_xticks` and `.set_xticklabels` on the current
+    axes.
+
+    Examples
+    --------
+    Get the current locations and labels:
+
+        >>> locs, labels = xticks()
+
+    Set label locations:
+
+        >>> xticks(np.arange(0, 1, step=0.2))
+
+    Set text labels:
 
-      # return locs, labels where locs is an array of tick locations and
-      # labels is an array of tick labels.
-      locs, labels = xticks()
+        >>> xticks(np.arange(5), ('Tom', 'Dick', 'Harry', 'Sally', 'Sue'))
 
-      # set the locations of the xticks
-      xticks( arange(6) )
 
-      # set the locations and labels of the xticks
-      xticks( arange(5), ('Tom', 'Dick', 'Harry', 'Sally', 'Sue') )
+        >>> xticks(np.arange(12), calendar.month_name[1:13], rotation=20)
 
-    The keyword args, if any, are :class:`~matplotlib.text.Text`
-    properties. For example, to rotate long labels::
+    Disable xticks:
 
-      xticks( arange(12), calendar.month_name[1:13], rotation=17 )
+        >>> xticks([])
     """
     ax = gca()
 
@@ -1672,24 +1708,60 @@ def xticks(*args, **kwargs):
 
 def yticks(*args, **kwargs):
     """
-    Get or set the *y*-limits of the current tick locations and labels.
+    Get or set the current tick locations and labels of the y-axis.
 
-    ::
+    Call signatures::
+
+        locs, labels = yticks()           # Get locations and labels
+
+        yticks(locs, [labels], **kwargs)  # Set locations and labels
+
+    Parameters
+    ----------
+    locs : array_like
+        A list of positions at which ticks should be placed.
+
+    labels : array_like, optional
+        A list of explicit labels to place the the given *locs*. You can pass
+        an empty list to disable yticks.
+
+    **kwargs
+        :class:`.Text` properties can be used to control the appearence of
+        the labels.
+
+    Returns
+    -------
+    locs
+        An array of label locations.
+    labels
+        A list of `.Text` objects.
+
+    Notes
+    -----
+    This is just a convenient shortcut for calling `.get_yticks` and
+    `.get_yticklabels` or `.set_yticks` and `.set_yticklabels` on the current
+    axes.
+
+    Examples
+    --------
+    Get the current locations and labels:
+
+        >>> locs, labels = yticks()
+
+    Set label locations:
+
+        >>> yticks(np.arange(0, 1, step=0.2))
+
+    Set text labels:
 
-      # return locs, labels where locs is an array of tick locations and
-      # labels is an array of tick labels.
-      locs, labels = yticks()
+        >>> yticks(np.arange(5), ('Tom', 'Dick', 'Harry', 'Sally', 'Sue'))
 
-      # set the locations of the yticks
-      yticks( arange(6) )
 
-      # set the locations and labels of the yticks
-      yticks( arange(5), ('Tom', 'Dick', 'Harry', 'Sally', 'Sue') )
+        >>> yticks(np.arange(12), calendar.month_name[1:13], rotation=45)
 
-    The keyword args, if any, are :class:`~matplotlib.text.Text`
-    properties. For example, to rotate long labels::
+    Disable yticks:
 
-      yticks( arange(12), calendar.month_name[1:13], rotation=45 )
+        >>> yticks([])
     """
     ax = gca()
 
