Merge pull request #10139 from dstansby/doc-handler

tacaswell · tacaswell · commit 01f95b105030 · 2018-01-16T23:16:07.000-05:00
DOC: Improve legend_handler docstrings

Conflicts:
	lib/matplotlib/legend_handler.py
          - whitespace conflicts around 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,7 +132,23 @@ 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.
+
+        numpoints : int
+            Number of points to show in legend entry.
+
+        Notes
+        -----
+        Any other keyword arguments are given to `HandlerBase`.
+        """
         HandlerBase.__init__(self, **kw)
 
         self._numpoints = numpoints
@@ -162,7 +177,25 @@ 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.
+
+        yoffsets : array of floats
+            Length *numpoints* list of y offsets for each point in
+            legend entry.
+
+        Notes
+        -----
+        Any other keyword arguments are given to `HandlerNpoints`.
+        """
         HandlerNpoints.__init__(self, numpoints=numpoints, **kw)
         self._yoffsets = yoffsets
 
@@ -177,10 +210,24 @@ 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):
-        HandlerNpoints.__init__(self, marker_pad=marker_pad, numpoints=numpoints, **kw)
+        """
+        Parameters
+        ----------
+        marker_pad : float
+            Padding between points in legend entry.
+
+        numpoints : int
+            Number of points to show in legend entry.
+
+        Notes
+        -----
+        Any other keyword arguments are given to `HandlerNpoints`.
+        """
+        HandlerNpoints.__init__(self, marker_pad=marker_pad,
+                                numpoints=numpoints, **kw)
 
     def create_artists(self, legend, orig_handle,
                        xdescent, ydescent, width, height, fontsize,
@@ -215,21 +262,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
@@ -256,7 +308,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:
@@ -288,7 +340,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)
@@ -302,7 +354,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):
@@ -363,7 +415,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]],
@@ -376,7 +428,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,
@@ -388,7 +440,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):
@@ -501,10 +553,29 @@ def create_artists(self, legend, orig_handle,
 
 class HandlerStem(HandlerNpointsYoffsets):
     """
-    Handler for Errorbars
+    Handler for plots produced by `~.Axes.stem`.
     """
     def __init__(self, marker_pad=0.3, numpoints=None,
                  bottom=None, yoffsets=None, **kw):
+        """
+        Parameters
+        ----------
+        marker_pad : float
+            Padding between points in legend entry. Default is 0.3.
+
+        numpoints : int, optional
+            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.
+
+        Notes
+        -----
+        Any other keyword arguments are given to `HandlerNpointsYoffsets`.
+        """
 
         HandlerNpointsYoffsets.__init__(self, marker_pad=marker_pad,
                                         numpoints=numpoints,
@@ -571,18 +642,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):
 
@@ -628,7 +695,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):
@@ -639,6 +706,7 @@ def first_color(colors):
                 return colors[0]
             else:
                 return "none"
+
         def get_first(prop_array):
             if len(prop_array):
                 return prop_array[0]
