Description
While working on #10148 I've come across https://matplotlib.org/api/_as_gen/matplotlib.axes.Axes.stem.html
I have the following questions.
1. Link to MATLAB
"See also" links to the MATLAB documentation. Do we really do this and is it meaningful? IMO the docs should be self-contained. There is no guarantee that the matplotlib and MATLAB APIs are or will stay compatible. I propose to simply remove the link.
2. keyword args
The signature is stem(*args, **kwargs)
. But it does only consider a limited list of 5 kwargs:
- linefmt
- markerfmt
- basefmt
- bottom
- label
Currently, all other arguments are silently ignored.
I propose to explicitly write the allowed arguments in the signature:
stem(*args, linefmt=None, markerfmt=None, basefmt=None, bottom=0, label=None)
AFAICS this should still be fully API compatible even with all variants of an injected data
keyword and the possibility to specify the formats as positional arguments.
The question is how to handle other kwargs. Options are:
a) still silently ignore them (no change)
b) raise a TypeError (breaks API compatibility, but would be the standard sane python behavior)
c) issue a warning
I tend to b) in this case.