fixed formatting to match our docstring conventions

brunobeltran · brunobeltran · commit b31c24134bff · 2020-04-10T01:00:29.000-07:00
diff --git a/lib/matplotlib/transforms.py b/lib/matplotlib/transforms.py
@@ -685,38 +685,60 @@ class Bbox(BboxBase):
 
     Examples
     --------
-    >>> # the default constructor takes the boundary "points" [[xmin, ymin],
-    >>> # [xmax, ymax]]
-    >>> unit_box = Bbox([[1, 1], [2, 2]])
+    The default constructor takes the boundary "points" ``[[xmin, ymin],
+    [xmax, ymax]]``.
 
-    >>> # the "zero" Bbox (i.e. "identity" object for Bbox.intersection), the
-    >>> # null bbox has (min, max) = (np.inf, -np.inf) for each dimension
-    >>> null = Bbox.null()
-    >>> assert unit_box == Bbox.intersection(unit_box, null)
+        >>> example_box = Bbox([[1, 1], [3, 7]])
+        >>> example_box
+        Bbox([[1.0, 1.0], [3.0, 7.0]])
 
-    >>> # and thus it overlaps with every bbox
-    >>> assert unit_bbox.overlaps(null)
+    Alternatively, a Bbox can be created from the flattened array, the
+    so-called "extents" ``(xmin, ymin, xmax, ymax)``
 
-    >>> # a union containing null (the "zero" Bbox) will always return null
-    >>> assert null == Bbox.union([unit_bbox, null])
+        >>> Bbox.from_extents(1, 1, 3, 7)
+        Bbox([[1.0, 1.0], [3.0, 7.0]])
 
-    >>> # a Bbox can be created from extents (xmin, ymin, xmax, ymax)
-    >>> assert unit_bbox == Bbox.from_extents(1, 1, 2, 2)
+    or from the "bounds" ``(xmin, ymin, width, height)``.
 
-    >>> # or from "bounds" (xmin, ymin, width, height)
-    >>> assert unit_bbox == Bbox.from_bounds(1, 1, 1, 1)
+        >>> Bbox.from_bounds(1, 1, 2, 6)
+        Bbox([[1.0, 1.0], [3.0, 7.0]])
 
-    >>> # or from an arbitrary list of points (here, 10 random points)
-    >>> random_bbox = Bbox.null()
-    >>> random_bbox.update_from_data_xy(np.random.rand((10, 2)))
+    The "empty" object for accumulating Bboxs is the null bbox, which has
+    ``(min, max) = (np.inf, -np.inf)`` for each dimension.
 
-    >>> # to quickly update a Bbox to include new point(s), simply use
-    >>> # `ignore=False`, it's faster than using `union` directly
-    >>> new_data = np.random.rand(10, 2)  # 10 new points
-    >>> new_bbox = Bbox.null()
-    >>> new_bbox.update_from_data_xy(new_data)
-    >>> assert random_bbox.update_from_data_xy(new_data, ignore=False) \
-    >>>     == Bbox.union([new_bbox, random_bbox])
+        >>> Bbox.null()
+        Bbox([[inf, inf], [-inf, -inf]])
+
+    Adding points to the null bbox will give you the bbox of those points.
+
+        >>> box = Bbox.null()
+        >>> box.update_from_data_xy([[1, 1]])
+        >>> box
+        Bbox([[1.0, 1.0], [1.0, 1.0]])
+        >>> box.update_from_data_xy([[2, 3], [3, 2]], ignore=False)
+        >>> box
+        Bbox([[1.0, 1.0], [3.0, 3.0]])
+
+    Setting ``ignore=True`` is equivalent to starting over from a null bbox.
+
+        >>> box.update_from_data_xy([[1, 1]], ignore=True)
+        >>> box
+        Bbox([[1.0, 1.0], [1.0, 1.0]])
+
+    The null bbox is also the identity for intersections
+
+        >>> Bbox.intersection(example_box, Bbox.null())
+        Bbox([[1.0, 1.0], [3.0, 7.0]])
+
+    except with itself, where it returns the full space.
+
+        >>> Bbox.intersection(Bbox.null(), Bbox.null())
+        Bbox([[-inf, -inf], [inf, inf]])
+
+    A union containing null will always return the full space (not null!)
+
+        >>> Bbox.union([example_box, Bbox.null()])
+        Bbox([[-inf, -inf], [inf, inf]])
     """
 
     def __init__(self, points, **kwargs):
@@ -729,8 +751,8 @@ def __init__(self, points, **kwargs):
         Notes
         -----
         If you need to create a `Bbox` object from another form
-        of data, consider the static methods :meth:`unit`,
-        :meth:`from_bounds` and :meth:`from_extents`.
+        of data, consider the static methods :meth:`from_bounds` and
+        :meth:`from_extents`.
         """
         BboxBase.__init__(self, **kwargs)
         points = np.asarray(points, float)
