Not necessarily to be done in this PR, but the docstring should be substantially enhanced to explain what this is for and how it works, some points are:

• you want second x axis, that is related to the x axis, e.g. show angles in degree and rad or show period and frequency
• this is realized by overlaying a child Axes and hiding all parts but its x axis.
• often, you do not add any data to the child Axes (and by default that does not make sense because it's y axis is hidden, so one cannot infer what y-values would belong to the data points.)
• One may contrast this with twin axes that share one axis but explicitly differ in the other axis to be able to show to different types of data overlaid.

Not sure to mention it, but IMHO the implementation as child Axes is a workaround implementation detail. A possibly cleaner, more general approach would be to support multiple axises on one Axes object.

Not sure to mention it, but IMHO the implementation as child Axes is a workaround implementation detail. A possibly cleaner, more general approach would be to support multiple axises on one Axes object.

If I recall, the main reason it is an Axes rather than an Axis, is that Axis does not have the concept of an x/ylabel - that is an Axes property. Similarly I think there are numerous tick conveniences on Axes that are less easy on Axis. Not to say one couldn't come up with an API for multiple xlabels etc, but simplest was just a child Axes.

While pragmatism tells me to merge this, this feels wrong. While we interpret type fields loosely target towards readability (instead of formal type specifications), the type field is not the place for context information. The minimal solution would be to move that to the description. OTOH, the underlying problem is that SecondaryAxes itself is not documented. It should be, and then the type link would redirect to the documentation.

Fair enough. I don't really have bandwidth to propose a better change right now, so let's just close this.

I've created #29004 as a reminder. Will care for it, when there is time.