Add some more explanatory comments to deprecations.

QuLogic · QuLogic · commit ebac2899f043 · 2020-08-21T16:06:15.000-04:00
diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py
@@ -435,6 +435,14 @@ def draw(self, renderer):
         # add the projection matrix to the renderer
         self.M = self.get_proj()
         props3d = {
+            # To raise a deprecation, we need to wrap the attribute in a
+            # function, but binding that to an instance does not work, as you
+            # would end up with an instance-specific method. Properties are
+            # class-level attributes which *are* functions, so we do that
+            # instead.
+            # This creates deprecated properties for the attributes listed
+            # below, and they are temporarily attached to the _class_ in the
+            # `_setattr_cm` call.
             name: cbook.deprecated('3.4', name=name,
                                    alternative=f'self.axes.{name}')(
                 property(lambda self, _value=getattr(self, name): _value))
@@ -443,8 +451,18 @@ def draw(self, renderer):
 
         with cbook._setattr_cm(type(renderer), **props3d):
             def do_3d_projection(artist):
+                """
+                Call `do_3d_projection` on an *artist*, and warn if passing
+                *renderer*.
+
+                For our Artists, never pass *renderer*. For external Artists,
+                in lieu of more complicated signature parsing, always pass
+                *renderer* and raise a warning.
+                """
+
                 if artist.__module__ == 'mpl_toolkits.mplot3d.art3d':
-                    # Our 3D Artists have deprecated the renderer parameter.
+                    # Our 3D Artists have deprecated the renderer parameter, so
+                    # avoid passing it to them.
                     return artist.do_3d_projection()
 
                 cbook.warn_deprecated(
