Documentation Link

No response

Problem

Inspired through the discussion at#28677 (comment): Through#20569 we have madeArtist.set() more useable. In particular, we have started toAxes.set() in some places in the documentation.

We currently do not have a best practice when toax.set_thing(foo) vsax.set(thing=foo).

Suggested improvement

We should have a best practive when to use what that we document, teach and use in our docs.

There was a loose discussion athttps://github.com/matplotlib/ProjectManagement/blob/b9b0a56cb7b329c3c2adfac77a84975f70868e24/meeting_notes/2021/q2.md#do-we-want-to-soup-up-and-advertise-objset-more, but no definitive solution.

General observations:

• Both APIs are intended to co-exist. We don't plan to get rid of one or the other.
• Advantages ofset_thing():
  • more specific
  • easier to find the docs (forset(thing=...) one has to go toset() and follow the link for the specific keyword).
  • more functionality through kwargs available
• Advantages ofset(thing=...):
  • shorter
• Neutral
  • tab completion should work for both cases (ax.set_<TAB> andax.set(<TAB>)
  • API is fully documented for both cases (no moreset(**kwargs) signatures)
  • Historicallyset_thing was mostly used and advertized

Please add if you have additional points.

I'll stop here without suggesting a solution to keep the discussion unbiased. Suggestions for solution should be posted as separte comments.