DOC: Explain return value of seconadary_x/yaxis (#31417)

timhoffm · web-flow · commit 39c906aceb8e · 2026-03-30T16:27:04.000-04:00
Follow up to #31405.
diff --git a/lib/matplotlib/axes/_secondary_axes.py b/lib/matplotlib/axes/_secondary_axes.py
@@ -329,6 +329,11 @@ def set_color(self, color):
 Returns
 -------
 ax : axes._secondary_axes.SecondaryAxis
+    The returned Axes is overlaid on top of the original Axes and all
+    components except for the complementary axis are hidden. You may modify
+    the complementary axis, e.g. by setting ticks or an axis label. However,
+    it is not designed to hold data, so that you should not call any
+    plotting methods on it.
 
 Other Parameters
 ----------------
