Merge pull request #14136 from timhoffm/auto-backport-of-pr-14109-on-v3.1.x

dstansby · web-flow · commit c206ea505d2e · 2019-05-06T09:35:30.000+01:00
Backport PR #14109 on branch v3.1.x
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -245,6 +245,7 @@ def switch_backend(newbackend):
 def show(*args, **kw):
     """
     Display a figure.
+
     When running in ipython with its pylab mode, display all
     figures and return to the ipython prompt.
 
@@ -338,6 +339,11 @@ def gci():
     :class:`~matplotlib.collections.Collection` instances.  The
     current image is an attribute of the current axes, or the nearest
     earlier axes in the current figure that contains an image.
+
+    Notes
+    -----
+    Historically, the only colorable artists were images; hence the name
+    ``gci`` (get current image).
     """
     return gcf()._gci()
 
@@ -426,7 +432,6 @@ def figure(num=None,  # autoincrement if None, else integer from 1-N
 
     Parameters
     ----------
-
     num : integer or string, optional, default: None
         If not provided, a new figure will be created, and the figure number
         will be incremented. The figure objects holds this number in a `number`
@@ -579,7 +584,12 @@ def _auto_draw_if_interactive(fig, val):
 
 
 def gcf():
-    """Get a reference to the current figure."""
+    """
+    Get the current figure.
+
+    If no current figure exists, a new one is created using
+    `~.pyplot.figure()`.
+    """
     figManager = _pylab_helpers.Gcf.get_active()
     if figManager is not None:
         return figManager.canvas.figure
@@ -606,9 +616,17 @@ def get_figlabels():
 
 def get_current_fig_manager():
     """
-    Return the figure manager of the active figure.
+    Return the figure manager of the current figure.
+
+    The figure manager is a container for the actual backend-depended window
+    that displays the figure on screen.
 
-    If there is currently no active figure, a new one is created.
+    If if no current figure exists, a new one is created an its figure
+    manager is returned.
+
+    Returns
+    -------
+    manager : `.FigureManagerBase` or backend-dependent subclass thereof
     """
     figManager = _pylab_helpers.Gcf.get_active()
     if figManager is None:
