From 3a425b73719dbd8eb05764000a9f88cdeeea1cc1 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Sat, 28 Mar 2026 08:16:53 +0100
Subject: [PATCH] DOC: Explain return value of seconadary_x/yaxis

Follow up to #31405.
---
 lib/matplotlib/axes/_secondary_axes.py | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/lib/matplotlib/axes/_secondary_axes.py b/lib/matplotlib/axes/_secondary_axes.py
index 08e706bba245..b373f2bd8ffd 100644
--- 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
 ----------------