Merge pull request matplotlib#11975 from anntzer/figlegend-docstring

Derive plt.figlegend.__doc__ from Figure.legend.__doc__.

Author: jklymak

lib/matplotlib/figure.py

@@ -1680,6 +1680,10 @@ def get_axes(self):
         """
         return self.axes
 
+    # Note: in the docstring below, the newlines in the examples after the
+    # calls to legend() allow replacing it with figlegend() to generate the
+    # docstring of pyplot.figlegend.
+
     @docstring.dedent_interpd
     def legend(self, *args, **kwargs):
         """
@@ -1691,15 +1695,17 @@ def legend(self, *args, **kwargs):
 
         To make a legend for a list of lines and labels::
 
-          legend( (line1, line2, line3),
-                  ('label1', 'label2', 'label3'),
-                  loc='upper right')
+          legend(
+              (line1, line2, line3),
+              ('label1', 'label2', 'label3'),
+              loc='upper right')
 
         These can also be specified by keyword::
 
-          legend(handles=(line1, line2, line3),
-                labels=('label1', 'label2', 'label3'),
-                loc='upper right')
+          legend(
+              handles=(line1, line2, line3),
+              labels=('label1', 'label2', 'label3'),
+              loc='upper right')
 
         Parameters
         ----------

lib/matplotlib/pyplot.py

@@ -756,41 +756,9 @@ def figimage(*args, **kwargs):
 
 
 def figlegend(*args, **kwargs):
-    """
-    Place a legend in the figure.
-
-    *labels*
-      a sequence of strings
-
-    *handles*
-      a sequence of :class:`~matplotlib.lines.Line2D` or
-      :class:`~matplotlib.patches.Patch` instances
-
-    *loc*
-      can be a string or an integer specifying the legend
-      location
-
-    A :class:`matplotlib.legend.Legend` instance is returned.
-
-    Examples
-    --------
-
-    To make a legend from existing artists on every axes::
-
-      figlegend()
-
-    To make a legend for a list of lines and labels::
-
-      figlegend( (line1, line2, line3),
-                 ('label1', 'label2', 'label3'),
-                 'upper right' )
-
-    .. seealso::
-
-       :func:`~matplotlib.pyplot.legend`
-
-    """
     return gcf().legend(*args, **kwargs)
+if Figure.legend.__doc__:
+    figlegend.__doc__ = Figure.legend.__doc__.replace("legend(", "figlegend(")
 
 
 ## Axes ##