Cleanup anchored_artists, inset_locator docstrings.

- Prefer string locations to integers (reusing the description used in
  the base AnchoredOffsetbox class).  Also switch from bullet list to
  plain text list (with correct layout in asciiart), as I think having
  the whole docstring fit in one screenful is also nice.
- Likewise, suppress blank lines between parameters (when all parameters
  have a single-paragraph description) to avoid really long docstrings.
- Group axes_class and axes_kwargs parameters together; also very
  slightly cleanup the implementation.
- Minor typo fixes.

Author: anntzer

lib/mpl_toolkits/axes_grid1/anchored_artists.py

@@ -24,39 +24,25 @@ def __init__(self, width, height, xdescent, ydescent,
         ----------
         width, height : float
             width and height of the container, in pixels.
-
         xdescent, ydescent : float
             descent of the container in the x- and y- direction, in pixels.
-
-        loc : int
-            Location of this artist. Valid location codes are::
-
-                'upper right'  : 1,
-                'upper left'   : 2,
-                'lower left'   : 3,
-                'lower right'  : 4,
-                'right'        : 5,
-                'center left'  : 6,
-                'center right' : 7,
-                'lower center' : 8,
-                'upper center' : 9,
-                'center'       : 10
-
+        loc : str
+            Location of this artist.  Valid locations are
+            'upper left', 'upper center', 'upper right',
+            'center left', 'center', 'center right',
+            'lower left', 'lower center, 'lower right'.
+            For backward compatibility, numeric values are accepted as well.
+            See the parameter *loc* of `.Legend` for details.
         pad : float, default: 0.4
             Padding around the child objects, in fraction of the font size.
-
         borderpad : float, default: 0.5
             Border padding, in fraction of the font size.
-
         prop : `matplotlib.font_manager.FontProperties`, optional
             Font property used as a reference for paddings.
-
         frameon : bool, default: True
             If True, draw a box around this artists.
-
         **kwargs
-            Keyworded arguments to pass to
-            :class:`matplotlib.offsetbox.AnchoredOffsetbox`.
+            Keyword arguments forwarded to `.AnchoredOffsetbox`.
 
         Attributes
         ----------
@@ -98,36 +84,23 @@ def __init__(self, transform, loc,
         transform : `matplotlib.transforms.Transform`
             The transformation object for the coordinate system in use, i.e.,
             :attr:`matplotlib.axes.Axes.transData`.
-
-        loc : int
-            Location of this artist. Valid location codes are::
-
-                'upper right'  : 1,
-                'upper left'   : 2,
-                'lower left'   : 3,
-                'lower right'  : 4,
-                'right'        : 5,
-                'center left'  : 6,
-                'center right' : 7,
-                'lower center' : 8,
-                'upper center' : 9,
-                'center'       : 10
-
+        loc : str
+            Location of this artist.  Valid locations are
+            'upper left', 'upper center', 'upper right',
+            'center left', 'center', 'center right',
+            'lower left', 'lower center, 'lower right'.
+            For backward compatibility, numeric values are accepted as well.
+            See the parameter *loc* of `.Legend` for details.
         pad : float, default: 0.4
             Padding around the child objects, in fraction of the font size.
-
         borderpad : float, default: 0.5
             Border padding, in fraction of the font size.
-
         prop : `matplotlib.font_manager.FontProperties`, optional
             Font property used as a reference for paddings.
-
         frameon : bool, default: True
             If True, draw a box around this artists.
-
         **kwargs
-            Keyworded arguments to pass to
-            :class:`matplotlib.offsetbox.AnchoredOffsetbox`.
+            Keyword arguments forwarded to `.AnchoredOffsetbox`.
 
         Attributes
         ----------
@@ -162,44 +135,28 @@ def __init__(self, transform, width, height, angle, loc,
         transform : `matplotlib.transforms.Transform`
             The transformation object for the coordinate system in use, i.e.,
             :attr:`matplotlib.axes.Axes.transData`.
-
         width, height : float
             Width and height of the ellipse, given in coordinates of
             *transform*.
-
         angle : float
             Rotation of the ellipse, in degrees, anti-clockwise.
-
-        loc : int
-            Location of this size bar. Valid location codes are::
-
-                'upper right'  : 1,
-                'upper left'   : 2,
-                'lower left'   : 3,
-                'lower right'  : 4,
-                'right'        : 5,
-                'center left'  : 6,
-                'center right' : 7,
-                'lower center' : 8,
-                'upper center' : 9,
-                'center'       : 10
-
-        pad : float, optional
-            Padding around the ellipse, in fraction of the font size. Defaults
-            to 0.1.
-
+        loc : str
+            Location of this ellipse.  Valid locations are
+            'upper left', 'upper center', 'upper right',
+            'center left', 'center', 'center right',
+            'lower left', 'lower center, 'lower right'.
+            For backward compatibility, numeric values are accepted as well.
+            See the parameter *loc* of `.Legend` for details.
+        pad : float, default: 0.1
+            Padding around the ellipse, in fraction of the font size.
         borderpad : float, default: 0.1
             Border padding, in fraction of the font size.
-
         frameon : bool, default: True
             If True, draw a box around the ellipse.
-
         prop : `matplotlib.font_manager.FontProperties`, optional
             Font property used as a reference for paddings.
-
         **kwargs
-            Keyworded arguments to pass to
-            :class:`matplotlib.offsetbox.AnchoredOffsetbox`.
+            Keyword arguments forwarded to `.AnchoredOffsetbox`.
 
         Attributes
         ----------
@@ -228,75 +185,54 @@ def __init__(self, transform, size, label, loc,
         transform : `matplotlib.transforms.Transform`
             The transformation object for the coordinate system in use, i.e.,
             :attr:`matplotlib.axes.Axes.transData`.
-
         size : float
             Horizontal length of the size bar, given in coordinates of
             *transform*.
-
         label : str
             Label to display.
-
-        loc : int
-            Location of this size bar. Valid location codes are::
-
-                'upper right'  : 1,
-                'upper left'   : 2,
-                'lower left'   : 3,
-                'lower right'  : 4,
-                'right'        : 5,
-                'center left'  : 6,
-                'center right' : 7,
-                'lower center' : 8,
-                'upper center' : 9,
-                'center'       : 10
-
+        loc : str
+            Location of this ellipse.  Valid locations are
+            'upper left', 'upper center', 'upper right',
+            'center left', 'center', 'center right',
+            'lower left', 'lower center, 'lower right'.
+            For backward compatibility, numeric values are accepted as well.
+            See the parameter *loc* of `.Legend` for details.
         pad : float, default: 0.1
             Padding around the label and size bar, in fraction of the font
             size.
-
         borderpad : float, default: 0.1
             Border padding, in fraction of the font size.
-
         sep : float, default: 2
             Separation between the label and the size bar, in points.
-
         frameon : bool, default: True
             If True, draw a box around the horizontal bar and label.
-
         size_vertical : float, default: 0
             Vertical length of the size bar, given in coordinates of
             *transform*.
-
         color : str, default: 'black'
             Color for the size bar and label.
-
         label_top : bool, default: False
             If True, the label will be over the size bar.
-
         fontproperties : `matplotlib.font_manager.FontProperties`, optional
             Font properties for the label text.
-
         fill_bar : bool, optional
             If True and if size_vertical is nonzero, the size bar will
             be filled in with the color specified by the size bar.
             Defaults to True if *size_vertical* is greater than
             zero and False otherwise.
-
         **kwargs
-            Keyworded arguments to pass to
-            :class:`matplotlib.offsetbox.AnchoredOffsetbox`.
+            Keyword arguments forwarded to `.AnchoredOffsetbox`.
 
         Attributes
         ----------
         size_bar : `matplotlib.offsetbox.AuxTransformBox`
             Container for the size bar.
-
         txt_label : `matplotlib.offsetbox.TextArea`
             Container for the label of the size bar.
 
         Notes
         -----
-        If *prop* is passed as a keyworded argument, but *fontproperties* is
+        If *prop* is passed as a keyword argument, but *fontproperties* is
         not, then *prop* is be assumed to be the intended *fontproperties*.
         Using both *prop* and *fontproperties* is not supported.
 
@@ -354,8 +290,8 @@ def __init__(self, transform, size, label, loc,
 
 class AnchoredDirectionArrows(AnchoredOffsetbox):
     def __init__(self, transform, label_x, label_y, length=0.15,
-                 fontsize=0.08, loc=2, angle=0, aspect_ratio=1, pad=0.4,
-                 borderpad=0.4, frameon=False, color='w', alpha=1,
+                 fontsize=0.08, loc='upper left', angle=0, aspect_ratio=1,
+                 pad=0.4, borderpad=0.4, frameon=False, color='w', alpha=1,
                  sep_x=0.01, sep_y=0, fontproperties=None, back_length=0.15,
                  head_width=10, head_length=15, tail_width=2,
                  text_props=None, arrow_props=None,
@@ -368,90 +304,61 @@ def __init__(self, transform, label_x, label_y, length=0.15,
         transform : `matplotlib.transforms.Transform`
             The transformation object for the coordinate system in use, i.e.,
             :attr:`matplotlib.axes.Axes.transAxes`.
-
         label_x, label_y : str
             Label text for the x and y arrows
-
         length : float, default: 0.15
             Length of the arrow, given in coordinates of *transform*.
-
         fontsize : float, default: 0.08
             Size of label strings, given in coordinates of *transform*.
-
-        loc : int, default: 2
-            Location of the direction arrows. Valid location codes are::
-
-                'upper right'  : 1,
-                'upper left'   : 2,
-                'lower left'   : 3,
-                'lower right'  : 4,
-                'right'        : 5,
-                'center left'  : 6,
-                'center right' : 7,
-                'lower center' : 8,
-                'upper center' : 9,
-                'center'       : 10
-
+        loc : str, default: 'upper left'
+            Location of this ellipse.  Valid locations are
+            'upper left', 'upper center', 'upper right',
+            'center left', 'center', 'center right',
+            'lower left', 'lower center, 'lower right'.
+            For backward compatibility, numeric values are accepted as well.
+            See the parameter *loc* of `.Legend` for details.
         angle : float, default: 0
             The angle of the arrows in degrees.
-
         aspect_ratio : float, default: 1
             The ratio of the length of arrow_x and arrow_y.
             Negative numbers can be used to change the direction.
-
         pad : float, default: 0.4
             Padding around the labels and arrows, in fraction of the font size.
-
         borderpad : float, default: 0.4
             Border padding, in fraction of the font size.
-
         frameon : bool, default: False
             If True, draw a box around the arrows and labels.
-
         color : str, default: 'white'
             Color for the arrows and labels.
-
         alpha : float, default: 1
             Alpha values of the arrows and labels
-
         sep_x, sep_y : float, default: 0.01 and 0 respectively
             Separation between the arrows and labels in coordinates of
             *transform*.
-
         fontproperties : `matplotlib.font_manager.FontProperties`, optional
             Font properties for the label text.
-
         back_length : float, default: 0.15
             Fraction of the arrow behind the arrow crossing.
-
         head_width : float, default: 10
             Width of arrow head, sent to ArrowStyle.
-
         head_length : float, default: 15
             Length of arrow head, sent to ArrowStyle.
-
         tail_width : float, default: 2
             Width of arrow tail, sent to ArrowStyle.
-
         text_props, arrow_props : dict
             Properties of the text and arrows, passed to
             `.textpath.TextPath` and `.patches.FancyArrowPatch`.
-
         **kwargs
-            Keyworded arguments to pass to
-            :class:`matplotlib.offsetbox.AnchoredOffsetbox`.
+            Keyword arguments forwarded to `.AnchoredOffsetbox`.
 
         Attributes
         ----------
         arrow_x, arrow_y : `matplotlib.patches.FancyArrowPatch`
             Arrow x and y
-
         text_path_x, text_path_y : `matplotlib.textpath.TextPath`
             Path for arrow labels
-
         p_x, p_y : `matplotlib.patches.PathPatch`
             Patch for arrow labels
-
         box : `matplotlib.offsetbox.AuxTransformBox`
             Container for the arrows and labels.