DOC: Document the parameter *position* of apply_aspect() as internal

Superseeds matplotlib#23629.

It is somewhat surprising that "_apply_aspect" takes an
optional position as input, which seems more functionality
than what the name suggests.

The parameter was introduced in 66290aa. Generally, applying
an aspect will modify the size and position of an Axes. The
fact that position is updated anyway was used to funnel
additional position information from a layout into the already
existing positioning code.

Deprecating and removing the parameter would be a medium compatibility
hassle. Therefore, I chose only to document the status quo and its
intention, so that users are less surprised. See
matplotlib#23629 (comment)

Author: timhoffm

lib/matplotlib/axes/_base.py

@@ -1881,6 +1881,11 @@ def apply_aspect(self, position=None):
         Parameters
         ----------
         position : None or .Bbox
+
+            .. note::
+                This parameter exists for historic reasons and is considered
+                internal. End users should not use it.
+
             If not ``None``, this defines the position of the
             Axes within the figure as a Bbox. See `~.Axes.get_position`
             for further details.
@@ -1891,6 +1896,10 @@ def apply_aspect(self, position=None):
         to call it yourself if you need to update the Axes position and/or
         view limits before the Figure is drawn.
 
+        An alternative with a broader scope is `.Figure.draw_without_rendering`,
+        which updates all stale components of a figure, not only the positioning /
+        view limits of a single Axes.
+
         See Also
         --------
         matplotlib.axes.Axes.set_aspect
@@ -1899,6 +1908,24 @@ def apply_aspect(self, position=None):
             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.figure.Figure.draw_without_rendering
+            Update all stale components of a figure.
+
+        Examples
+        --------
+        A typical usage example would be the following. `~.Axes.imshow` sets the
+        aspect to 1, but adapting the Axes position and extent to reflect this is
+        deferred until rendering for performance reasons. If you want to know the
+        Axes size before, you need to call `.apply_aspect` to get the correct
+        values.
+
+        >>> fig, ax = plt.subplots()
+        >>> ax.imshow(np.zeros((3, 3)))
+        >>> ax.bbox.width, ax.bbox.height
+        (496.0, 369.59999999999997)
+        >>> ax.apply_aspect()
+        >>> ax.bbox.width, ax.bbox.height
+        (369.59999999999997, 369.59999999999997)
         """
         if position is None:
             position = self.get_position(original=True)