I agree that one should probably not copy the arrowprops part, but maybe something like

arrowprops: dict, optional
    Arrow properties, see `.Annotation` for description.

fontsize: float or str, optional
    Font size, see `~Text.set_fontsize`.

?

As these properties are explicit in the constructor. (fontsize is documented as part of **kwargs in Annotation as "Additional kwargs are passed to Text" and not directly documented in Text either... One may wonder why it is explicitly mentioned in AnnotationBbox.

Turns out that annotation_clip is also missing...

Anyway, no strong opinions as such (I can always add those later), but I'll leave it for a while to see if someone has stronger opinions.

Now I look deeper, I think having "Other parameters are identical to Annotation" next to **kwargs here is also wrong, or at least misleading. It implies that this **kwargs would include Annotation's **kwargs, which are passed to Text, as you say. But AnnotationBbox's **kwargs are passed to self._internal_update. So maybe the **kwargs description here should reference e.g. the set method?

I think I have addressed all the comments, but...

What text does this fontsize keyword apply to? If I put e.g. fontsize="xx-large" in the call to AnnotationBbox in my example at #24390, it doesn't seem to make a difference. That makes sense, as you would set the fontsize for the text in the box using the TextArea object instead. Is there some other text associated with the AnnotationBbox?

What text does this fontsize keyword apply to?

Looking into the code, the fontsize parameter is stored in a FontPropertiesobject at AnnotationBbox.prop and its only use is to define the mutation_scale parameter of the FancyBboxPatch, i.e. affecting attributes of the box style like padding and rounding of corners (if defined).

AFAICS we should rename fontsize to mutation_scale and deprecate prop. But ping @anntzer, who wrote this code in 2009.

I didn't really look at what piece of code you're talking about (can you point out the line?) but I was certainly not involved with matplotlib development yet in 2009...

I think mutation_scale can be passed as part of bboxprops, so we could just deprecate fontsize and direct the user to use bboxprops=dict(mutation_scale=x) instead? It would seem odd to me to have mutation_scale accessible at the top level when the other FancyBboxPatch parameters (like boxstyle) are passed within the dictionary.

I didn't really look at what piece of code you're talking about (can you point out the line?) but I was certainly not involved with matplotlib development yet in 2009...

Sorry, mixed up users. - Just read the short version "09.08.09 Lee", but it was @leejjoon. @leejjoon do you rember the motivation in AnnotationBbox to pass fontsize -> self.prop -> FancyBboxPatch(..., mutation_scale=...)?

it indeed seems that mutation_scale can be passed already via bboxprops and the fontsize parameter is not needed at all.

I guess using fontsize gives the user the convenience of passing a string, rather than points. Also it currently defaults to rcParams["legend.fontsize"]. If we left it to the FancyBBoxPatch default of 1, it would presumably look quite cramped.

So perhaps using fontsize is the most practical way to get a nice looking pad, etc., even though we are not dealing with any actual fonts.

Edit: AnchoredOffsetbox does something similar with the prop parameter.

My vague recollection is that I wanted to copy the behavior from annotation (and text) that the mutation scale is set to their fontsize. As @rcomer commented in his post, I think this was a sensible thing to do. The parameter name of fontsize could be misleading and may need to be replaced. It would be good if we can keep the current behavior, though.

@timhoffm I have updated the fontsize description to explain how it is used. Do you think this is enough? Once we understand the reasoning, the name does not seem wrong to me. Perhaps a little unintuitive, but I wonder if that matters enough to go through the breaking change procedure.

Thanks @rcomer! I appreciate this work. It's often more cumbersome than initially expected, but it really makes our docs much better.