Documentation Link

No response

Problem

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

We currently do not have a best practice when to ax.set_thing(foo) vs ax.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 at https://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 of set_thing():
  • more specific
  • easier to find the docs (for set(thing=...) one has to go to set() and follow the link for the specific keyword).
  • more functionality through kwargs available
• Advantages of set(thing=...):
  • shorter
• Neutral
  • tab completion should work for both cases (ax.set_<TAB> and ax.set(<TAB>)
  • API is fully documented for both cases (no more set(**kwargs) signatures)
  • Historically set_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.