Merge pull request #10139 from dstansby/doc-handler

tacaswell · web-flow · commit c176df460660 · 2018-01-08T15:54:26.000-05:00
DOC: Improve legend_handler docstrings
diff --git a/lib/matplotlib/legend_handler.py b/lib/matplotlib/legend_handler.py
@@ -18,11 +18,10 @@
 i.e., this is dpi-scaled value).
 
 This module includes definition of several legend handler classes
-derived from the base class (HandlerBase) with the following method.
+derived from the base class (HandlerBase) with the following method::
 
     def legend_artist(self, legend, orig_handle, fontsize, handlebox):
 
-
 """
 from __future__ import (absolute_import, division, print_function,
                         unicode_literals)
@@ -133,19 +132,22 @@ def create_artists(self, legend, orig_handle,
 
 
 class HandlerNpoints(HandlerBase):
+    """
+    A legend handler that shows *numpoints* points in the legend entry.
+    """
     def __init__(self, marker_pad=0.3, numpoints=None, **kw):
         """
         Parameters
         ----------
         marker_pad : float
-            Padding between points in legend entry
+            Padding between points in legend entry.
 
         numpoints : int
-            Number of points to show in legend entry
+            Number of points to show in legend entry.
 
         Notes
         -----
-        Any other keyword arguments are given to `HandlerBase`
+        Any other keyword arguments are given to `HandlerBase`.
         """
         HandlerBase.__init__(self, **kw)
 
@@ -174,19 +176,24 @@ def get_xdata(self, legend, xdescent, ydescent, width, height, fontsize):
 
 
 class HandlerNpointsYoffsets(HandlerNpoints):
+    """
+    A legend handler that shows *numpoints* in the legend, and allows them to
+    be individually offest in the y-direction.
+    """
     def __init__(self, numpoints=None, yoffsets=None, **kw):
         """
         Parameters
         ----------
         numpoints : int
-            Number of points to show in legend entry
+            Number of points to show in legend entry.
 
         yoffsets : array of floats
-            Length *numpoints* list of y offsets for each point in legend entry
+            Length *numpoints* list of y offsets for each point in
+            legend entry.
 
         Notes
         -----
-        Any other keyword arguments are given to `HandlerNpoints`
+        Any other keyword arguments are given to `HandlerNpoints`.
         """
         HandlerNpoints.__init__(self, numpoints=numpoints, **kw)
         self._yoffsets = yoffsets
@@ -202,21 +209,21 @@ def get_ydata(self, legend, xdescent, ydescent, width, height, fontsize):
 
 class HandlerLine2D(HandlerNpoints):
     """
-    Handler for Line2D instances.
+    Handler for `.Line2D` instances.
     """
     def __init__(self, marker_pad=0.3, numpoints=None, **kw):
         """
         Parameters
         ----------
         marker_pad : float
-            Padding between points in legend entry
+            Padding between points in legend entry.
 
         numpoints : int
-            Number of points to show in legend entry
+            Number of points to show in legend entry.
 
         Notes
         -----
-        Any other keyword arguments are given to `HandlerNpoints`
+        Any other keyword arguments are given to `HandlerNpoints`.
         """
         HandlerNpoints.__init__(self, marker_pad=marker_pad,
                                 numpoints=numpoints, **kw)
@@ -254,21 +261,26 @@ def create_artists(self, legend, orig_handle,
 
 class HandlerPatch(HandlerBase):
     """
-    Handler for Patch instances.
+    Handler for `.Patch` instances.
     """
     def __init__(self, patch_func=None, **kw):
         """
-        The HandlerPatch class optionally takes a function ``patch_func``
-        who's responsibility is to create the legend key artist. The
-        ``patch_func`` should have the signature::
+        Parameters
+        ----------
+        patch_func : callable, optional
+            The function that creates the legend key artist.
+            *patch_func* should have the signature::
 
-            def patch_func(legend=legend, orig_handle=orig_handle,
-                           xdescent=xdescent, ydescent=ydescent,
-                           width=width, height=height, fontsize=fontsize)
+                def patch_func(legend=legend, orig_handle=orig_handle,
+                               xdescent=xdescent, ydescent=ydescent,
+                               width=width, height=height, fontsize=fontsize)
 
-        Subsequently the created artist will have its ``update_prop`` method
-        called and the appropriate transform will be applied.
+            Subsequently the created artist will have its ``update_prop`` method
+            called and the appropriate transform will be applied.
 
+        Notes
+        -----
+        Any other keyword arguments are given to `HandlerBase`.
         """
         HandlerBase.__init__(self, **kw)
         self._patch_func = patch_func
@@ -295,7 +307,7 @@ def create_artists(self, legend, orig_handle,
 
 class HandlerLineCollection(HandlerLine2D):
     """
-    Handler for LineCollection instances.
+    Handler for `.LineCollection` instances.
     """
     def get_numpoints(self, legend):
         if self._numpoints is None:
@@ -327,7 +339,7 @@ def create_artists(self, legend, orig_handle,
 
 class HandlerRegularPolyCollection(HandlerNpointsYoffsets):
     """
-    Handler for RegularPolyCollections.
+    Handler for `.RegularPolyCollections`.
     """
     def __init__(self, yoffsets=None, sizes=None, **kw):
         HandlerNpointsYoffsets.__init__(self, yoffsets=yoffsets, **kw)
@@ -341,7 +353,7 @@ def get_numpoints(self, legend):
             return self._numpoints
 
     def get_sizes(self, legend, orig_handle,
-                 xdescent, ydescent, width, height, fontsize):
+                  xdescent, ydescent, width, height, fontsize):
         if self._sizes is None:
             handle_sizes = orig_handle.get_sizes()
             if not len(handle_sizes):
@@ -402,7 +414,7 @@ def create_artists(self, legend, orig_handle,
 
 class HandlerPathCollection(HandlerRegularPolyCollection):
     """
-    Handler for PathCollections, which are used by scatter
+    Handler for `.PathCollections`, which are used by `~.Axes.scatter`.
     """
     def create_collection(self, orig_handle, sizes, offsets, transOffset):
         p = type(orig_handle)([orig_handle.get_paths()[0]],
@@ -415,7 +427,7 @@ def create_collection(self, orig_handle, sizes, offsets, transOffset):
 
 class HandlerCircleCollection(HandlerRegularPolyCollection):
     """
-    Handler for CircleCollections
+    Handler for `.CircleCollections`.
     """
     def create_collection(self, orig_handle, sizes, offsets, transOffset):
         p = type(orig_handle)(sizes,
@@ -427,7 +439,7 @@ def create_collection(self, orig_handle, sizes, offsets, transOffset):
 
 class HandlerErrorbar(HandlerLine2D):
     """
-    Handler for Errorbars
+    Handler for Errorbars.
     """
     def __init__(self, xerr_size=0.5, yerr_size=None,
                  marker_pad=0.3, numpoints=None, **kw):
@@ -540,7 +552,7 @@ def create_artists(self, legend, orig_handle,
 
 class HandlerStem(HandlerNpointsYoffsets):
     """
-    Handler for plots produced by `stem`
+    Handler for plots produced by `~.Axes.stem`.
     """
     def __init__(self, marker_pad=0.3, numpoints=None,
                  bottom=None, yoffsets=None, **kw):
@@ -551,16 +563,17 @@ def __init__(self, marker_pad=0.3, numpoints=None,
             Padding between points in legend entry. Default is 0.3.
 
         numpoints : int, optional
-            Number of points to show in legend entry
+            Number of points to show in legend entry.
 
         bottom : float, optional
 
         yoffsets : array of floats, optional
-            Length *numpoints* list of y offsets for each point in legend entry
+            Length *numpoints* list of y offsets for each point in
+            legend entry.
 
         Notes
         -----
-        Any other keyword arguments are given to `HandlerNpointsYoffsets`
+        Any other keyword arguments are given to `HandlerNpointsYoffsets`.
         """
 
         HandlerNpointsYoffsets.__init__(self, marker_pad=marker_pad,
@@ -628,18 +641,14 @@ class HandlerTuple(HandlerBase):
 
     Parameters
     ----------
-
     ndivide : int, optional
-        The number of sections to divide the legend area into.  If None,
+        The number of sections to divide the legend area into. If None,
         use the length of the input tuple. Default is 1.
 
 
     pad : float, optional
-        If None, fall back to `legend.borderpad` as the default.
+        If None, fall back to ``legend.borderpad`` as the default.
         In units of fraction of font size. Default is None.
-
-
-
     """
     def __init__(self, ndivide=1, pad=None, **kwargs):
 
@@ -681,7 +690,7 @@ def create_artists(self, legend, orig_handle,
 
 class HandlerPolyCollection(HandlerBase):
     """
-    Handler for PolyCollection used in fill_between and stackplot.
+    Handler for `.PolyCollection` used in `~.Axes.fill_between` and `~.Axes.stackplot`.
     """
     def _update_prop(self, legend_handle, orig_handle):
         def first_color(colors):
@@ -692,6 +701,7 @@ def first_color(colors):
                 return colors[0]
             else:
                 return "none"
+
         def get_first(prop_array):
             if len(prop_array):
                 return prop_array[0]
