DOC/MNT: Address reviewer feedback on add_collection docstring and autoscale semantics

tinezivic · tinezivic · commit a1c58ec13809 · 2026-04-21T06:32:21.000+02:00
- Revert autolim docstring first line to original user-facing wording
  ("update data and view limits" instead of internal "request autoscaling")
- Adopt reviewer suggestion for If-False clause: "does not take part in
  any limit operations"
- Expand versionchanged:: 3.11 note to explain both pre-3.11 behavior
  and the new relim participation (per reviewer suggestion)
- Move _set_in_autoscale(True) inside if autolim: block (simpler and
  consistent with how add_line/add_patch/add_image do it)
- Update stale TODO in Artist.remove: the "collections relim problem"
  referenced has been fixed; rephrase to reflect the remaining
  long-term architectural goal
diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py
@@ -268,10 +268,10 @@ def remove(self):
 
         else:
             raise NotImplementedError('cannot remove artist')
-        # TODO: the fix for the collections relim problem is to move the
-        # limits calculation into the artist itself, including the property of
-        # whether or not the artist should affect the limits.  Then there will
-        # be no distinction between axes.add_line, axes.add_patch, etc.
+        # TODO: move the limits calculation into the artist itself, including
+        # the property of whether or not the artist should affect the limits.
+        # Then there will be no distinction between axes.add_line,
+        # axes.add_patch, etc.
         # TODO: add legend support
 
     def have_units(self):
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -2384,15 +2384,23 @@ def add_collection(self, collection, autolim=True):
         collection : `.Collection`
             The collection to add.
         autolim : bool
-            Whether to update data limits and request autoscaling.
+            Whether to update data and view limits.
 
-            If *False*, the collection is explicitly excluded from
-            `~.Axes.relim`.
+            If *False*, the collection does not take part in any limit
+            operations.
 
             .. versionchanged:: 3.11
 
-               This now also updates the view limits, making explicit
-               calls to `~.Axes.autoscale_view` unnecessary.
+               Since 3.11 `autolim=True` matches the standard behavior
+               of other ``add_[artist]`` methods: Axes data and view limits
+               are both updated in the method, and the collection will
+               be considered in future data limit updates through
+               `.relim`.
+
+               Prior to matplotlib 3.11 this was only a one-time update
+               of the data limits. Updating view limits required an
+               explicit calls to `~.Axes.autoscale_view`, and collections
+               did not take part in `.relim`.
 
             As an implementation detail, the value "_datalim_only" is
             supported to smooth the internal transition from pre-3.11
@@ -2409,11 +2417,8 @@ def add_collection(self, collection, autolim=True):
         if collection.get_clip_path() is None:
             collection.set_clip_path(self.patch)
 
-        # Keep relim() participation aligned with the autolim argument.
-        # autolim can also be the internal sentinel "_datalim_only".
-        collection._set_in_autoscale(bool(autolim))
-
         if autolim:
+            collection._set_in_autoscale(True)
             # Make sure viewLim is not stale (mostly to match
             # pre-lazy-autoscale behavior, which is not really better).
             self._unstale_viewLim()
