Side note, maybe not enough to change in hindsight, but to set future practice:

I would generally favor set_thing(x) over set(thing=x) for single properties.

And in this particular example, I would also have kept the two properties ax1.set(ylim=(-1.5, 1.5), title="axhspan") above separate. Mainly because of symmetry with ax2.set_title and to a lesser degree because ylim and title are quite different properties.

I'm the opposite in that I prefer .set for properties that aren't the focus of the example and we don't need any of the other kwargs, mostly b/c so many folks complain "why must I write all this boilerplate" and this is less boilerplate.

Axes.set() is similar to pyplot. It's a convenience interface that people can use to simplify their code - if they know what they are doing, but it does not provide the full capability. I'd say: If you only want to learn or teach the minimal stuff, stick with set_*(). Only when it's a real simplification, use set(). - Possibly this is something we should discuss and agree on a strategy, like wie did with Axes-interface vs. pyplot. It's not helpful if the docs do it one way or the other depending on the author.

Looked up if we did in the meeting notes and agreeing that first step is probably writing a user guide entry:

• https://github.com/matplotlib/ProjectManagement/blob/b9b0a56cb7b329c3c2adfac77a84975f70868e24/meeting_notes/2021/q2.md#do-we-want-to-soup-up-and-advertise-objset-more

Thanks for digging that up 🚀. I'm sure I advocated for "advertise set() more". But I don't agree with

one-shot set aimed at use cases who are using us as an application and the set_XYZ for when we are being used internal to a third-party library.

That's not the criterion for me. Instead, I would like to advertise set() as a shortcut. As API lead I see the need and call for a discussion on how we consider and in which cases we want to advertise set().

I'm fine w/ a new discussion and then us documenting the decision at https://matplotlib.org/devdocs/devel/style_guide.html#terminology, please add it to the agenda for a week you'll be on the call or maybe open an issue? (we really need a consistent way to do not call based/asynch discussions)

The set_title method is far more featureful and should usually be preferred to set(title=) unless there is some reason to be concise. Using nonstandard patterns trips up reading an example and I don't think there is a strong argument to use "set" as a standard.

My reasons for conciseness were:

• Setting the title isn't an important part of this PR, it's done here mostly to quickly line up figure w/ method b/c there are two being demoed
• The set method is a good way to quickly handle a bunch of boilerplate where you don't need the kwargs, b/c frequent complaint is too much boilerplate

That being said:

1. As discussed in the meeting, this may be better handled by a new user guide entry/rework of the artists guide (and a section of the quick start guide for set on axis)
2. I'm fine if consensus is that examples get set _*, but then it needs to get documented

set_title method is far more featureful

Yes, but none of those features are needed for this example and if someone needs those features they can look at one of our set_title examples?

Discussion moved to #28693