Merge pull request #18694 from anntzer/deprecated-mi

tacaswell · web-flow · commit 8e6d87e578ca · 2020-10-08T20:50:13.000-04:00
DOC: Document limitations on `@deprecated` with multiple-inheritance.
diff --git a/lib/matplotlib/cbook/deprecation.py b/lib/matplotlib/cbook/deprecation.py
@@ -119,6 +119,12 @@ def deprecated(since, *, message='', name='', alternative='', pending=False,
     ``@staticmethod`` (i.e., `deprecated` should directly decorate the
     underlying callable), but *over* ``@property``.
 
+    When deprecating a class ``C`` intended to be used as a base class in a
+    multiple inheritance hierarchy, ``C`` *must* define an ``__init__`` method
+    (if ``C`` instead inherited its ``__init__`` from its own base class, then
+    ``@deprecated`` would mess up ``__init__`` inheritance when installing its
+    own (deprecation-emitting) ``C.__init__``).
+
     Parameters
     ----------
     since : str
