I would just pick some reasonable argument names (levels, allsegs and allkinds are fine, but you can also change them if you want as they were positional-only up to now) and transform this into a regular signature without custom parsing.

I agree with the proposed change, but will leave it to a separate PR.

It's probably simple enough. I did not touch this, because there's a bit of code paths to change with_process_args and maybe subclasses. I try to keep the docstring updates separated from really non-trivial code changes. This eases reviewing as well as backporting.

If array-like, draw contour lines [at / on / through ?] the specified level values.

or

If array-like, contour the specified level values.

Since contour could be a verb?

Defaults to.MaxNLocator.

or

By default,.MaxNLocator is used.

Why does theAxes.contour documentation link to thepyplot.contour documentation (which is the same)?

Same in the Notes section (line 1792 ..)

Given the discussion in#10974 it might be sensible to keep the links to pyplot as the pyplot function docs have a gallery below them.

This same docstring is used both on the Axes and pyplot interfaces, because we don't want to maintain to almost identical versions. For this we have to pay the small price that both versions link to the same functions. We have the same issue with other passthrough functions. I've left the links as they are.

This should actually link to the QuadContourSet docs,

:class:`~matplotlib.contour.QuadContourSet` object.

(modulo correct syntax)

Although this example list is long, I think it makes much more sense than the 1-liner that has replaced it above, so I would be keen to keep these lines.

You mean the stuff beforeOptional keyword arguments? Comparingold andnew, this is mostly repetitive stuff:

• Draw Z,
• Draw Z with X, Y
• Draw Z with parameter N
• Draw Z with X, Y and parameter N
• Draw Z with parameter V (which is just a more explicit control of the same property controlled by N)
• Draw Z with X, Y and parameter N (which is just a more explicit control of the same property controlled by N)

It's much easier to say and understand:

• Draw Z, optionally with X, Y and optionally with giving the levels.

I was really happy that I could boil this section down to quite a simple formula. To me it was really daunting before. I find it quite demotivating to read the doc at all, when I have to read a full screen before I have an idea, what parameters I could use.

One might add a sentence after the call signature, "where Z are the values, X, Y are the coordinates, ..". But then again, that's just a repetition of the parameter section, which is immediately following.

Can you explain the benefit you see in the long version?

I agree that there is a long list there, but I thinkcontour([X, Y,] Z, [levels], **kwargs) is too terse, and confusing (can I do(X, Z)?(Z, levels)? e.g.). I think having a list of the allowable call signatures would be much better, and it could be boiled down to

• contour(Z ...)
• contour(X, Y, Z ...)

with some sort of explanation thatlevels can be provided before keyword arguments.

Well by definition, the square brackets meanoptional. You can use or leave out every square bracket separately. So,X, Z does not work, butZ, levels does.

It's maybe a question if everybody knows this convention. I'd rather use a standard python function signature instead. However that's not possible with optional positional parameters, which are often used in matplotlib. Anyway, I'm still in favor of using the standard convention for optional parameters compared to verbosely giving multiple alternatives.

I could add a sentence "X, Y must be given both, or left out both." to the paramter description, if that adds additional clarity.