Merge pull request matplotlib#24444 from rcomer/annotation-doc

DOC: AnnotationBbox keyword descriptions

Author: timhoffm

examples/text_labels_and_annotations/demo_annotation_box.py

@@ -31,7 +31,8 @@
                     xybox=(-20, 40),
                     xycoords='data',
                     boxcoords="offset points",
-                    arrowprops=dict(arrowstyle="->"))
+                    arrowprops=dict(arrowstyle="->"),
+                    bboxprops=dict(boxstyle="sawtooth"))
 ax.add_artist(ab)
 
 # Annotate the 1st position with another text box ('Test')
@@ -54,11 +55,12 @@
 da.add_artist(p)
 
 ab = AnnotationBbox(da, xy,
-                    xybox=(1.02, xy[1]),
+                    xybox=(1., xy[1]),
                     xycoords='data',
                     boxcoords=("axes fraction", "data"),
-                    box_alignment=(0., 0.5),
-                    arrowprops=dict(arrowstyle="->"))
+                    box_alignment=(0.2, 0.5),
+                    arrowprops=dict(arrowstyle="->"),
+                    bboxprops=dict(alpha=0.5))
 
 ax.add_artist(ab)
 

lib/matplotlib/offsetbox.py

@@ -1257,6 +1257,16 @@ def __init__(self, offsetbox, xy,
             (accessible as the ``patch`` attribute of the `.AnnotationBbox`).
             If *frameon* is set to False, this patch is made invisible.
 
+        annotation_clip: bool or None, default: None
+            Whether to clip (i.e. not draw) the annotation when the annotation
+            point *xy* is outside the axes area.
+
+            - If *True*, the annotation will be clipped when *xy* is outside
+              the axes.
+            - If *False*, the annotation will always be drawn.
+            - If *None*, the annotation will be clipped when *xy* is outside
+              the axes and *xycoords* is 'data'.
+
         pad : float, default: 0.4
             Padding around the offsetbox.
 
@@ -1265,8 +1275,25 @@ def __init__(self, offsetbox, xy,
             the offset box w.r.t. the *boxcoords*.
             The lower-left corner is (0, 0) and upper-right corner is (1, 1).
 
+        bboxprops : dict, optional
+            A dictionary of properties to set for the annotation bounding box,
+            for example *boxstyle* and *alpha*.  See `.FancyBboxPatch` for
+            details.
+
+        arrowprops: dict, optional
+            Arrow properties, see `.Annotation` for description.
+
+        fontsize: float or str, optional
+            Translated to points and passed as *mutation_scale* into
+            `.FancyBboxPatch` to scale attributes of the box style (e.g. pad
+            or rounding_size).  The name is chosen in analogy to `.Text` where
+            *fontsize* defines the mutation scale as well.  If not given,
+            :rc:`legend.fontsize` is used.  See `.Text.set_fontsize` for valid
+            values.
+
         **kwargs
-            Other parameters are identical to `.Annotation`.
+            Other `AnnotationBbox` properties.  See `.AnnotationBbox.set` for
+            a list.
         """
 
         martist.Artist.__init__(self)