Various documentation changes

jmehne · Julian Mehne · commit c721a1567ea8 · 2016-03-19T09:46:07.000+01:00
- Add what's new entry
- Update legend guide
- Document HandlerTuple's default values
diff --git a/doc/users/legend_guide.rst b/doc/users/legend_guide.rst
@@ -198,6 +198,21 @@ following example demonstrates combining two legend keys on top of one another:
 
     plt.legend([red_dot, (red_dot, white_cross)], ["Attr A", "Attr A+B"])
 
+The :class:`~matplotlib.legend_handler.HandlerTuple` class can also be used to
+assign several legend keys to the same entry:
+
+.. plot::
+    :include-source:
+
+    import matplotlib.pyplot as plt
+    from matplotlib.legend_handler import HandlerLine2D, HandlerTuple
+
+    p1, = plt.plot([1, 2.5, 3], 'r-d')
+    p2, = plt.plot([3, 2, 1], 'k-o')
+
+    l = plt.legend([(p1, p2)], ['Two keys'], numpoints=1,
+                   handler_map={tuple: HandlerTuple(ndivide=0)})
+
 
 Implementing a custom legend handler
 ------------------------------------
diff --git a/doc/users/whats_new/multiple_legend_keys.rst b/doc/users/whats_new/multiple_legend_keys.rst
@@ -0,0 +1,10 @@
+Multiple legend keys for legend entries
+---------------------------------------
+
+A legend entry can now contain more than one legend key. The extended
+``HandlerTuple`` class now accepts two parameters: ``ndivide`` divides the
+legend area in the specified number of sections; ``pad`` changes the padding
+between the legend keys.
+
+.. plot:: mpl_examples/pylab_examples/legend_demo6.py
+
diff --git a/lib/matplotlib/legend_handler.py b/lib/matplotlib/legend_handler.py
@@ -577,12 +577,12 @@ class HandlerTuple(HandlerBase):
 
     ndivide : int, optional
         The number of sections to divide the legend area into.  If 0,
-        use the length of the input tuple.
+        use the length of the input tuple. Default is 1.
 
 
     pad : float, optional
         If None, fall back to `legend.borderpad` as the default.
-        In units of fraction of font size.
+        In units of fraction of font size. Default is None.
 
 
 
