docstring: clarify usage of Figure.add_axes

efiring · efiring · commit 4bafdfc4ecf4 · 2011-08-12T20:25:57.000-10:00
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -633,27 +633,28 @@ def fixlist(args):
     @docstring.dedent_interpd
     def add_axes(self, *args, **kwargs):
         """
-        Add an a axes with axes rect [*left*, *bottom*, *width*,
+        Add an axes at position *rect* [*left*, *bottom*, *width*,
         *height*] where all quantities are in fractions of figure
         width and height.  kwargs are legal
         :class:`~matplotlib.axes.Axes` kwargs plus *projection* which
         sets the projection type of the axes.  (For backward
         compatibility, ``polar=True`` may also be provided, which is
         equivalent to ``projection='polar'``).  Valid values for
-        *projection* are: %(projection_names)s.  Some of these projections support
-        additional kwargs, which may be provided to :meth:`add_axes`::
+        *projection* are: %(projection_names)s.  Some of these
+        projections support  additional kwargs, which may be provided
+        to :meth:`add_axes`. Typical usage::
 
             rect = l,b,w,h
             fig.add_axes(rect)
             fig.add_axes(rect, frameon=False, axisbg='g')
             fig.add_axes(rect, polar=True)
             fig.add_axes(rect, projection='polar')
-            fig.add_axes(ax)   # add an Axes instance
+            fig.add_axes(ax)
 
         If the figure already has an axes with the same parameters,
         then it will simply make that axes current and return it.  If
-        you do not want this behavior, eg. you want to force the
-        creation of a new axes, you must use a unique set of args and
+        you do not want this behavior, e.g. you want to force the
+        creation of a new Axes, you must use a unique set of args and
         kwargs.  The axes :attr:`~matplotlib.axes.Axes.label`
         attribute has been exposed for this purpose.  Eg., if you want
         two axes that are otherwise identical to be added to the
@@ -662,9 +663,18 @@ def add_axes(self, *args, **kwargs):
             fig.add_axes(rect, label='axes1')
             fig.add_axes(rect, label='axes2')
 
-        The :class:`~matplotlib.axes.Axes` instance will be returned.
+        In rare circumstances, add_axes may be called with a single
+        argument, an Axes instance already created in the present
+        figure but not in the figure's list of axes.  For example,
+        if an axes has been removed with :meth:`delaxes`, it can
+        be restored with::
 
-        The following kwargs are supported:
+            fig.add_axes(ax)
+
+        In all cases, the :class:`~matplotlib.axes.Axes` instance
+        will be returned.
+
+        In addition to *projection*, the following kwargs are supported:
 
         %(Axes)s
         """
@@ -1321,7 +1331,7 @@ def tight_layout(self, renderer=None, pad=1.2, h_pad=None, w_pad=None):
         nrows_list = []
         ncols_list = []
         ax_bbox_list = []
-        
+
         subplot_dict = {} # for axes_grid1, multiple axes can share
                           # same subplot_interface. Thus we need to
                           # join them together.
@@ -1348,7 +1358,7 @@ def tight_layout(self, renderer=None, pad=1.2, h_pad=None, w_pad=None):
                 subplotspec_list.append(subplotspec)
                 subplot_list.append(subplots)
                 ax_bbox_list.append(subplotspec.get_position(self))
-                
+
             subplots.append(ax)
 
         max_nrows = max(nrows_list)
