Document how to check for the existence of current figure/axes.

Author: anntzer

lib/matplotlib/figure.py

@@ -1484,7 +1484,13 @@ def sca(self, a):
     @docstring.dedent_interpd
     def gca(self, **kwargs):
         """
-        Get the current Axes, creating one if necessary.
+        Get the current Axes.
+
+        If there is currently no Axes on this Figure, a new one is created
+        using `.Figure.add_subplot`.  (To test whether there is currently an
+        Axes on a Figure, check whether ``figure.axes`` is empty.  To test
+        whether there is currently a Figure on the pyplot figure stack, check
+        whether `.pyplot.get_fignums()` is empty.)
 
         The following kwargs are supported for ensuring the returned Axes
         adheres to the given projection etc., and for Axes creation if

lib/matplotlib/pyplot.py

@@ -819,8 +819,10 @@ def gcf():
     """
     Get the current figure.
 
-    If no current figure exists, a new one is created using
-    `~.pyplot.figure()`.
+    If there is currently no figure on the pyplot figure stack, a new one is
+    created using `~.pyplot.figure()`.  (To test whether there is currently a
+    figure on the pyplot figure stack, check whether `~.pyplot.get_fignums()`
+    is empty.)
     """
     manager = _pylab_helpers.Gcf.get_active()
     if manager is not None: