DOC: improve docstrings

tacaswell · timhoffm · web-flow · commit 6e0ba4cb3b9b · 2022-08-26T14:05:06.000-04:00
Co-authored-by: Tim Hoffmann &lt;2836374+timhoffm@users.noreply.github.com&gt;
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -709,7 +709,7 @@ def __init_subclass__(cls, **kwargs):
                 pending=True,
                 message=f'Overriding `Axes.cla` in {cls.__qualname__} is '
                 'pending deprecation in %(since)s and will be fully '
-                'deprecated for `Axes.clear` in the future. Please report '
+                'deprecated in favor of `Axes.clear` in the future. Please report '
                 f'this to the {cls.__module__!r} author.')
         cls._subclass_uses_cla = 'cla' in cls.__dict__ or parent_uses_cla
         super().__init_subclass__(**kwargs)
@@ -1216,7 +1216,11 @@ def sharey(self, other):
 
     def _clear(self):
         """Clear the Axes."""
-        # Note: this is called by Axes.__init__()
+        # The actual implementation of clear() as long as clear() has to be
+        # an adapter delegating to the correct implementation.
+        # The implementation can move back into clear() when the
+        # deprecation on cla() subclassing expires.
+        
 
         # stash the current visibility state
         if hasattr(self, 'patch'):
