Merge pull request #9951 from timhoffm/doc-axes-position

jklymak · web-flow · commit 40eb83f3e84f · 2017-12-11T16:55:56.000-08:00
Improve documentation on Axes position
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -854,36 +854,44 @@ def _update_transScale(self):
                     pass
 
     def get_position(self, original=False):
-        'Return the a copy of the axes rectangle as a Bbox'
+        """
+        Get a copy of the axes rectangle as a `.Bbox`.
+
+        Parameters
+        ----------
+        original : bool
+            If ``True``, return the original position. Otherwise return the
+            active position. For an explanation of the positions see
+            `.set_position`.
+
+        Returns
+        -------
+        pos : `.Bbox`
+
+        """
         if original:
             return self._originalPosition.frozen()
         else:
             return self._position.frozen()
 
     def set_position(self, pos, which='both'):
-        """Set the axes position
-
-        The expected shape of ``pos`` is::
+        """
+        Set the axes position.
 
-          pos = [left, bottom, width, height]
+        Axes have two position attributes. The 'original' position is the
+        position allocated for the Axes. The 'active' position is the
+        position the Axes is actually drawn at. These positions are usually
+        the same unless a fixed aspect is set to the Axes. See `.set_aspect`
+        for details.
 
-        in relative 0,1 coords, or *pos* can be a
-        :class:`~matplotlib.transforms.Bbox`
+        Parameters
+        ----------
+        pos : [left, bottom, width, height] or `~matplotlib.transforms.Bbox`
+            The new position of the in `.Figure` coordinates.
 
-        There are two position variables: one which is ultimately
-        used, but which may be modified by :meth:`apply_aspect`, and a
-        second which is the starting point for :meth:`apply_aspect`.
+        which : ['both' | 'active' | 'original'], optional
+            Determines which position variables to change.
 
-        Optional keyword arguments:
-          *which*
-
-            ==========   ====================
-            value        description
-            ==========   ====================
-            'active'     to change the first
-            'original'   to change the second
-            'both'       to change both
-            ==========   ====================
         """
         if not isinstance(pos, mtransforms.BboxBase):
             pos = mtransforms.Bbox.from_bounds(*pos)
@@ -894,7 +902,12 @@ def set_position(self, pos, which='both'):
         self.stale = True
 
     def reset_position(self):
-        """Make the original position the active position"""
+        """
+        Reset the active position to the original position.
+
+        This resets the a possible position change due to aspect constraints.
+        For an explanation of the positions see `.set_position`.
+        """
         pos = self.get_position(original=True)
         self.set_position(pos, which='active')
 
@@ -917,7 +930,7 @@ def set_axes_locator(self, locator):
 
     def get_axes_locator(self):
         """
-        return axes_locator
+        Return the axes_locator.
         """
         return self._axes_locator
 
@@ -1114,10 +1127,11 @@ def axesPatch(self):
         return self.patch
 
     def clear(self):
-        """clear the axes"""
+        """Clear the axes."""
         self.cla()
 
     def get_facecolor(self):
+        """Get the Axes facecolor."""
         return self.patch.get_facecolor()
     get_fc = get_facecolor
 
@@ -1226,7 +1240,7 @@ def ishold(self):
     @cbook.deprecated("2.0", message=_hold_msg)
     def hold(self, b=None):
         """
-        Set the hold state
+        Set the hold state.
 
         The ``hold`` mechanism is deprecated and will be removed in
         v3.0.  The behavior will remain consistent with the
