DOC: Document that set_aspect applies the aspect lazily

Makes the effect in matplotlib#31232 easier to understand.
Helps a bit clarifying the original vs. active position concept matplotlib#31254.

Author: timhoffm

lib/matplotlib/axes/_base.py

@@ -1268,7 +1268,8 @@ def sharex(self, other):
         another Axes.  Note that it is not possible to unshare axes.
         """
         _api.check_isinstance(_AxesBase, other=other)
-        if self._sharex is not None and other is not self._sharex:
+        siblings = self._shared_axes["x"]
+        if self._is_xaxis_shared() is not None and other is not self._sharex:
             raise ValueError("x-axis is already shared")
         self._shared_axes["x"].join(self, other)
         self._sharex = other
@@ -1297,6 +1298,14 @@ def sharey(self, other):
         self.set_ylim(y0, y1, emit=False, auto=other.get_autoscaley_on())
         self.yaxis._scale = other.yaxis._scale
 
+    def _is_xaxis_shared(self):
+        """Return whether the x-axis is shared with any other Axes."""
+        return bool(self._shared_axes["x"].get_siblings(include_self=False))
+
+    def _is_yaxis_shared(self):
+        """Return whether the y-axis is shared with any other Axes."""
+        return bool(self._shared_axes["Y"].get_siblings(include_self=False))
+
     def __clear(self):
         """Clear the Axes."""
         # The actual implementation of clear() as long as clear() has to be
@@ -1406,10 +1415,10 @@ def __clear(self):
         self.xaxis.set_clip_path(self.patch)
         self.yaxis.set_clip_path(self.patch)
 
-        if self._sharex is not None:
+        if self._is_xaxis_shared():
             self.xaxis.set_visible(xaxis_visible)
             self.patch.set_visible(patch_visible)
-        if self._sharey is not None:
+        if self._is_yaxis_shared():
             self.yaxis.set_visible(yaxis_visible)
             self.patch.set_visible(patch_visible)
 
@@ -1700,12 +1709,21 @@ def set_aspect(self, aspect, adjustable=None, anchor=None, share=False):
         share : bool, default: False
             If ``True``, apply the settings to all shared Axes.
 
+        Notes
+        -----
+        The aspect will require an update of the Axes position or limits (which
+        one depends on *adjustable*). This update is applied lazily, the latest
+        when the figure is drawn. Use `.apply_aspect` to force an update.
+
         See Also
         --------
         matplotlib.axes.Axes.set_adjustable
             Set how the Axes adjusts to achieve the required aspect ratio.
         matplotlib.axes.Axes.set_anchor
             Set the position in case of extra space.
+        matplotlib.axes.Axes.apply_aspect
+            Force the update required to meet the aspect ratio to happen
+            immediately.
         """
         if cbook._str_equal(aspect, 'equal'):
             aspect = 1