Skip to content

Question on docstring and signature of Axes.stem() #10151

Closed
@timhoffm

Description

@timhoffm

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.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions