Add some legend handler documentation (#9575)

dstansby · NelleV · commit 6aeeec7efde2 · 2017-10-26T10:16:52.000-07:00
* Small fix in legend_guide

* Add some docstrings to legend_handler.py

* DOC use double quotes for docstring

The convention is to use triple "double quotes", and not single quotes.
diff --git a/lib/matplotlib/legend_handler.py b/lib/matplotlib/legend_handler.py
@@ -90,7 +90,7 @@ def adjust_drawing_area(self, legend, orig_handle,
         return xdescent, ydescent, width, height
 
     def legend_artist(self, legend, orig_handle,
-                       fontsize, handlebox):
+                      fontsize, handlebox):
         """
         Return the artist that this HandlerBase generates for the given
         original artist/handle.
@@ -134,6 +134,19 @@ def create_artists(self, legend, orig_handle,
 
 class HandlerNpoints(HandlerBase):
     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
@@ -160,9 +173,21 @@ def get_xdata(self, legend, xdescent, ydescent, width, height, fontsize):
         return xdata, xdata_marker
 
 
-
 class HandlerNpointsYoffsets(HandlerNpoints):
     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
 
@@ -180,7 +205,21 @@ class HandlerLine2D(HandlerNpoints):
     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,
@@ -396,10 +435,11 @@ def __init__(self, xerr_size=0.5, yerr_size=None,
         self._xerr_size = xerr_size
         self._yerr_size = yerr_size
 
-        HandlerLine2D.__init__(self, marker_pad=marker_pad, numpoints=numpoints,
-                               **kw)
+        HandlerLine2D.__init__(self, marker_pad=marker_pad,
+                               numpoints=numpoints, **kw)
 
-    def get_err_size(self, legend, xdescent, ydescent, width, height, fontsize):
+    def get_err_size(self, legend, xdescent, ydescent,
+                     width, height, fontsize):
         xerr_size = self._xerr_size * fontsize
 
         if self._yerr_size is None:
@@ -421,7 +461,6 @@ def create_artists(self, legend, orig_handle,
         ydata = ((height - ydescent) / 2.) * np.ones(xdata.shape, float)
         legline = Line2D(xdata, ydata)
 
-
         xdata_marker = np.asarray(xdata_marker)
         ydata_marker = np.asarray(ydata[:len(xdata_marker)])
 
@@ -501,10 +540,28 @@ def create_artists(self, legend, orig_handle,
 
 class HandlerStem(HandlerNpointsYoffsets):
     """
-    Handler for Errorbars
+    Handler for plots produced by `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,
diff --git a/tutorials/intermediate/legend_guide.py b/tutorials/intermediate/legend_guide.py
@@ -46,8 +46,8 @@
 not all artists can be added to a legend, at which point a "proxy" will have
 to be created (see :ref:`proxy_legend_handles` for further details).
 
-# For full control of what is being added to the legend, it is common to pass
-# the appropriate handles directly to :func:`legend`
+For full control of what is being added to the legend, it is common to pass
+the appropriate handles directly to :func:`legend`::
 
     line_up, = plt.plot([1,2,3], label='Line 2')
     line_down, = plt.plot([3,2,1], label='Line 1')
