Merge pull request #18106 from timhoffm/legend-labels

jkseppan · web-flow · commit 2c170f4f6893 · 2020-08-02T12:17:50.000+03:00
Copy docstring description from Axes.legend() to Figure.legend()
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -323,8 +323,8 @@ def legend(self, *args, **kwargs):
             legend(labels)
             legend(handles, labels)
 
-        The call signatures correspond to three different ways how to use
-        this method.
+        The call signatures correspond to these three different ways to use
+        this method:
 
         **1. Automatic detection of elements to be shown in the legend**
 
@@ -335,7 +335,7 @@ def legend(self, *args, **kwargs):
         them either at artist creation or by calling the
         :meth:`~.Artist.set_label` method on the artist::
 
-            line, = ax.plot([1, 2, 3], label='Inline label')
+            ax.plot([1, 2, 3], label='Inline label')
             ax.legend()
 
         or::
@@ -360,7 +360,7 @@ def legend(self, *args, **kwargs):
             ax.plot([1, 2, 3])
             ax.legend(['A simple line'])
 
-        Note: This way of using is discouraged, because the relation between
+        Note: This call signature is discouraged, because the relation between
         plot elements and labels is only implicit by their order and can
         easily be mixed up.
 
@@ -371,7 +371,7 @@ def legend(self, *args, **kwargs):
         to pass an iterable of legend artists followed by an iterable of
         legend labels respectively::
 
-            legend((line1, line2, line3), ('label1', 'label2', 'label3'))
+            ax.legend([line1, line2, line3], ['label1', 'label2', 'label3'])
 
         Parameters
         ----------
@@ -398,6 +398,10 @@ def legend(self, *args, **kwargs):
         ----------------
         %(_legend_kw_doc)s
 
+        See Also
+        --------
+        .Figure.legend
+
         Notes
         -----
         Some artists are not supported by this function.  See
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1891,23 +1891,62 @@ def legend(self, *args, **kwargs):
         """
         Place a legend on the figure.
 
-        To make a legend from existing artists on every axes::
+        Call signatures::
+
+            legend()
+            legend(labels)
+            legend(handles, labels)
+
+        The call signatures correspond to these three different ways to use
+        this method:
+
+        **1. Automatic detection of elements to be shown in the legend**
+
+        The elements to be added to the legend are automatically determined,
+        when you do not pass in any extra arguments.
+
+        In this case, the labels are taken from the artist. You can specify
+        them either at artist creation or by calling the
+        :meth:`~.Artist.set_label` method on the artist::
+
+            ax.plot([1, 2, 3], label='Inline label')
+            fig.legend()
+
+        or::
+
+            line, = ax.plot([1, 2, 3])
+            line.set_label('Label via method')
+            fig.legend()
 
-          legend()
+        Specific lines can be excluded from the automatic legend element
+        selection by defining a label starting with an underscore.
+        This is default for all artists, so calling `.Figure.legend` without
+        any arguments and without setting the labels manually will result in
+        no legend being drawn.
 
-        To make a legend for a list of lines and labels::
 
-          legend(
-              (line1, line2, line3),
-              ('label1', 'label2', 'label3'),
-              loc='upper right')
+        **2. Labeling existing plot elements**
 
-        These can also be specified by keyword::
+        To make a legend for all artists on all Axes, call this function with
+        an iterable of strings, one for each legend item. For example::
 
-          legend(
-              handles=(line1, line2, line3),
-              labels=('label1', 'label2', 'label3'),
-              loc='upper right')
+            fig, (ax1, ax2)  = plt.subplots(1, 2)
+            ax1.plot([1, 3, 5], color='blue')
+            ax2.plot([2, 4, 6], color='red')
+            fig.legend(['the blues', 'the reds'])
+
+        Note: This call signature is discouraged, because the relation between
+        plot elements and labels is only implicit by their order and can
+        easily be mixed up.
+
+
+        **3. Explicitly defining the elements in the legend**
+
+        For full control of which artists have a legend entry, it is possible
+        to pass an iterable of legend artists followed by an iterable of
+        legend labels respectively::
+
+            fig.legend([line1, line2, line3], ['label1', 'label2', 'label3'])
 
         Parameters
         ----------
@@ -1934,6 +1973,10 @@ def legend(self, *args, **kwargs):
         ----------------
         %(_legend_kw_doc)s
 
+        See Also
+        --------
+        .Axes.legend
+
         Notes
         -----
         Some artists are not supported by this function.  See
