Reword add_subplot docstring.

anntzer · anntzer · commit 00cea3e5d126 · 2019-04-25T11:21:58.000+02:00
- Move description of the "rare" case to where that parameter is
  described.
- Make return type fit in one line, avoiding an awkward line
  continuation or bunch of spaces in the unrendered docs.
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1281,6 +1281,10 @@ def add_subplot(self, *args, **kwargs):
 
             If no positional arguments are passed, defaults to (1, 1, 1).
 
+            In rare circumstances, `.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.
+
         projection : {None, 'aitoff', 'hammer', 'lambert', 'mollweide', \
 'polar', 'rectilinear', str}, optional
             The projection type of the subplot (`~.axes.Axes`). *str* is the
@@ -1310,8 +1314,7 @@ def add_subplot(self, *args, **kwargs):
 
         Returns
         -------
-        axes : an `.axes.SubplotBase` subclass of `~.axes.Axes` (or a \
-               subclass of `~.axes.Axes`)
+        axes : `.axes.SubplotBase`, or another subclass of `~.axes.Axes`
 
             The axes of the subplot. The returned axes base class depends on
             the projection used. It is `~.axes.Axes` if rectilinear projection
@@ -1330,10 +1333,6 @@ def add_subplot(self, *args, **kwargs):
         two subplots that are otherwise identical to be added to the figure,
         make sure you give them unique labels.
 
-        In rare circumstances, `.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.
-
         See Also
         --------
         .Figure.add_axes
