Improve docstrings in offsetbox.py

timhoffm · timhoffm · commit c0a5864e1110 · 2020-01-05T22:12:32.000+01:00
diff --git a/doc/api/offsetbox_api.rst b/doc/api/offsetbox_api.rst
@@ -2,7 +2,7 @@
 ``matplotlib.offsetbox``
 ************************
 
-.. inheritance-diagram:: matplotlib.offsetbox.OffsetBox matplotlib.offsetbox.PackerBase matplotlib.offsetbox.VPacker matplotlib.offsetbox.HPacker matplotlib.offsetbox.PaddedBox matplotlib.offsetbox.DrawingArea matplotlib.offsetbox.TextArea matplotlib.offsetbox.AuxTransformBox matplotlib.offsetbox.AnchoredOffsetbox matplotlib.offsetbox.AnchoredText matplotlib.offsetbox.OffsetImage matplotlib.offsetbox.AnnotationBbox matplotlib.offsetbox.DraggableBase matplotlib.offsetbox.DraggableOffsetBox matplotlib.offsetbox.DraggableAnnotation
+.. inheritance-diagram:: matplotlib.offsetbox
    :parts: 1
 
 .. automodule:: matplotlib.offsetbox
diff --git a/lib/matplotlib/offsetbox.py b/lib/matplotlib/offsetbox.py
@@ -2,7 +2,7 @@
 Container classes for `.Artist`\s.
 
 `OffsetBox`
-    The base of all container artists.
+    The base of all container artists defined in this module.
 
 `AnchoredOffsetbox`, `AnchoredText`
     Anchor and align an arbitrary `.Artist` or a text relative to the parent
@@ -16,11 +16,10 @@
     Containers for layouting their children vertically or horizontally.
 
 `PaddedBox`
-    A container for add a padding around an `.Artist`.
+    A container to add a padding around an `.Artist`.
 
 `TextArea`
     Contains a single `.Text` instance.
-
 """
 
 import numpy as np
@@ -396,8 +395,8 @@ def __init__(self, pad=None, sep=None, width=None, height=None,
 
         Notes
         -----
-        *pad* and *sep* need to be given in points and will be scaled with
-        the renderer dpi, while *width* and *height* need to be in pixels.
+        *pad* and *sep* are in points and will be scaled with the renderer
+        dpi, while *width* and *height* are in in pixels.
         """
         super().__init__()
 
@@ -449,8 +448,8 @@ def __init__(self, pad=None, sep=None, width=None, height=None,
 
         Notes
         -----
-        *pad* and *sep* need to be given in points and will be scaled with
-        the renderer dpi, while *width* and *height* need to be in pixels.
+        *pad* and *sep* are in points and will be scaled with the renderer
+        dpi, while *width* and *height* are in in pixels.
         """
         super().__init__(pad, sep, width, height, align, mode, children)
 
@@ -527,8 +526,8 @@ def __init__(self, pad=None, sep=None, width=None, height=None,
 
         Notes
         -----
-        *pad* and *sep* need to be given in points and will be scaled with
-        the renderer dpi, while *width* and *height* need to be in pixels.
+        *pad* and *sep* are in points and will be scaled with the renderer
+        dpi, while *width* and *height* are in in pixels.
         """
         super().__init__(pad, sep, width, height, align, mode, children)
 
@@ -1012,12 +1011,12 @@ def draw(self, renderer):
 
 class AnchoredOffsetbox(OffsetBox):
     """
-    A container of an `.OffsetBox` placing it according to location *loc*.
+    An offset box placed according to location *loc*.
 
-    AnchoredOffsetbox has a single child. When multiple children
-    is needed, use other OffsetBox class to enclose them.  By default,
-    the offset box is anchored against its parent axes. You may
-    explicitly specify the bbox_to_anchor.
+    AnchoredOffsetbox has a single child.  When multiple children are needed,
+    use an extra OffsetBox to enclose them.  By default, the offset box is
+    anchored against its parent axes. You may explicitly specify the
+    *bbox_to_anchor*.
     """
     zorder = 5  # zorder of the legend
 
@@ -1044,27 +1043,20 @@ def __init__(self, loc,
         Parameters
         ----------
         loc : str
-            The box location.
-
-            For back-compatibility, ``'center right'`` (but no other location)
-            can also be spelled ``'right'``, and each "string" locations can
-            also be given as a numeric value:
-
-            ===============   =============
-            Location String   Location Code
-            ===============   =============
-            'best'            0
-            '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
-            ===============   =============
+            The box location. Supported values:
+
+            - 'upper right'
+            - 'upper left'
+            - 'lower left'
+            - 'lower right'
+            - 'center left'
+            - 'center right'
+            - 'lower center'
+            - 'upper center'
+            - 'center'
+
+            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 as fraction of the fontsize.
@@ -1279,9 +1271,6 @@ def _get_anchored_bbox(self, loc, bbox, parentbbox, borderpad):
 class AnchoredText(AnchoredOffsetbox):
     """
     AnchoredOffsetbox with Text.
-
-    This is a convenience class. Technically, it is just an `AnchoredOffsetbox`
-    containing a `TextArea`.
     """
 
     def __init__(self, s, loc, pad=0.4, borderpad=0.5, prop=None, **kwargs):
