DOC: update pyplot.subplot docstring

tacaswell · tacaswell · commit bad4195bc64a · 2021-02-10T23:54:01.000-05:00
diff --git a/doc/users/next_whats_new/axes_kwargs_collision.rst b/doc/users/next_whats_new/axes_kwargs_collision.rst
@@ -3,19 +3,19 @@ Changes to behavior of Axes creation methods (``gca()``, ``add_axes()``, ``add_s
 
 The behavior of the functions to create new axes (`.pyplot.axes`,
 `.pyplot.subplot`, `.figure.Figure.add_axes`,
-`.figure.Figure.add_subplot`) has changed. In the past, these functions would
-detect if you were attempting to create Axes with the same keyword arguments as
-already-existing axes in the current figure, and if so, they would return the
-existing Axes. Now, these functions will always create new Axes. A special
-exception is `.pyplot.subplot`, which will reuse any existing subplot with a
-matching subplot spec. However, if there is a subplot with a matching subplot
-spec, then that subplot will be returned, even if the keyword arguments with
-which it was created differ.
+`.figure.Figure.add_subplot`) has changed.  In the past, these
+functions would detect if you were attempting to create Axes with the
+same keyword arguments as already-existing axes in the current figure,
+and if so, they would return the existing Axes.  Now, `.pyplot.axes`,
+`.figure.Figure.add_axes`, and `.figure.Figure.add_subplot` will
+always create new Axes.  `.pyplot.subplot` will continue reuse an
+existing Axes with a matching subplot spec and equal *kwargs*.
 
 Correspondingly, the behavior of the functions to get the current Axes
-(`.pyplot.gca`, `.figure.Figure.gca`) has changed. In the past, these functions
-accepted keyword arguments. If the keyword arguments matched an
-already-existing Axes, then that Axes would be returned, otherwise new Axes
-would be created with those keyword arguments. Now, the keyword arguments are
-only considered if there are no axes at all in the current figure. In a future
-release, these functions will not accept keyword arguments at all.
+(`.pyplot.gca`, `.figure.Figure.gca`) has changed.  In the past, these
+functions accepted keyword arguments.  If the keyword arguments
+matched an already-existing Axes, then that Axes would be returned,
+otherwise new Axes would be created with those keyword arguments.
+Now, the keyword arguments are only considered if there are no axes at
+all in the current figure. In a future release, these functions will
+not accept keyword arguments at all.
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -1072,10 +1072,10 @@ def cla():
 @docstring.dedent_interpd
 def subplot(*args, **kwargs):
     """
-    Add a subplot to the current figure.
+    Add an Axes to the current figure or retrieve an existing Axes.
 
-    Wrapper of `.Figure.add_subplot` with a difference in
-    behavior explained in the notes section.
+    This is a wrapper of `.Figure.add_subplot` which provides additional
+    behavior when working with the implicit API (see the notes section).
 
     Call signatures::
 
@@ -1142,8 +1142,8 @@ def subplot(*args, **kwargs):
 
     Notes
     -----
-    Creating a subplot will delete any pre-existing subplot that overlaps
-    with it beyond sharing a boundary::
+    Creating a new Axes will delete any pre-existing Axes that
+    overlaps with it beyond sharing a boundary::
 
         import matplotlib.pyplot as plt
         # plot a line, implicitly creating a subplot(111)
@@ -1156,18 +1156,10 @@ def subplot(*args, **kwargs):
     If you do not want this behavior, use the `.Figure.add_subplot` method
     or the `.pyplot.axes` function instead.
 
-    If the figure already has a subplot with key (*args*,
-    *kwargs*) then it will simply make that subplot current and
-    return it.  This behavior is deprecated. Meanwhile, if you do
-    not want this behavior (i.e., you want to force the creation of a
-    new subplot), you must use a unique set of args and kwargs.  The axes
-    *label* attribute has been exposed for this purpose: if you want
-    two subplots that are otherwise identical to be added to the figure,
-    make sure you give them unique labels.
-
-    In rare circumstances, `.Figure.add_subplot` may be called with a single
-    argument, a subplot axes instance already created in the
-    present figure but not in the figure's list of axes.
+    If the current Figure already has an Axes created with the same
+    (*args*, *kwargs*) the existing Axes will be made current and
+    returned.  If the values in *kwargs* are mutable this may not
+    behave as expected.
 
     See Also
     --------
@@ -1183,10 +1175,10 @@ def subplot(*args, **kwargs):
         plt.subplot(221)
 
         # equivalent but more general
-        ax1=plt.subplot(2, 2, 1)
+        ax1 = plt.subplot(2, 2, 1)
 
         # add a subplot with no frame
-        ax2=plt.subplot(222, frameon=False)
+        ax2 = plt.subplot(222, frameon=False)
 
         # add a polar subplot
         plt.subplot(223, projection='polar')
@@ -1199,6 +1191,10 @@ def subplot(*args, **kwargs):
 
         # add ax2 to the figure again
         plt.subplot(ax2)
+
+        # make the first axes "current" again
+        plt.subplot(221)
+
     """
 
     # if subplot called without arguments, create subplot(1, 1, 1)
