Description
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 toset()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>andax.set(<TAB>) - API is fully documented for both cases (no more
set(**kwargs)signatures) - Historically
set_thingwas mostly used and advertized
- tab completion should work for both cases (
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.