Document API changes for Axes sublists.

QuLogic · QuLogic · commit e44514045d7b · 2020-08-26T22:10:22.000-04:00
diff --git a/doc/api/next_api_changes/behavior/18216-ES.rst b/doc/api/next_api_changes/behavior/18216-ES.rst
@@ -0,0 +1,30 @@
+.. _Behavioral API Changes 3.4 - Axes children combined:
+
+``Axes`` children are no longer separated by type
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Formerly, `.axes.Axes` children were separated by `.Artist` type, into sublists
+such as ``Axes.lines``. For methods that produced multiple elements (such as
+`.Axes.errorbar`), though individual parts would have similar *zorder*, this
+separation might cause them to be drawn at different times, causing
+inconsistent results when overlapping other Artists.
+
+Now, the children are no longer separated by type, and the sublist properties
+are generated dynamically when accessed. Consequently, Artists will now always
+appear in the correct sublist; e.g., if `.axes.Axes.add_line` is called on a
+`.Patch`, it will be appear in the ``Axes.patches`` sublist, _not_
+``Axes.lines``. The ``Axes.add_*`` methods will now warn if passed an
+unexpected type.
+
+Modification of the following sublists is still accepted, but deprecated:
+
+* ``Axes.artists``
+* ``Axes.collections``
+* ``Axes.images``
+* ``Axes.lines``
+* ``Axes.patches``
+* ``Axes.tables``
+* ``Axes.texts``
+
+To remove an Artist, use its `.Artist.remove` method. To add an Artist, use the
+corresponding ``Axes.add_*`` method.
diff --git a/doc/api/next_api_changes/deprecations/18216-ES.rst b/doc/api/next_api_changes/deprecations/18216-ES.rst
@@ -0,0 +1,22 @@
+Modification of ``Axes`` children sublists
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+See :ref:`Behavioral API Changes 3.4 - Axes children combined` for more
+information; modification of the following sublists is deprecated:
+
+* ``Axes.artists``
+* ``Axes.collections``
+* ``Axes.images``
+* ``Axes.lines``
+* ``Axes.patches``
+* ``Axes.tables``
+* ``Axes.texts``
+
+To remove an Artist, use its `.Artist.remove` method. To add an Artist, use the
+corresponding ``Axes.add_*`` method.
+
+Passing incorrect types to ``Axes.add_*`` methods
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``Axes.add_*`` methods will now warn if passed an unexpected type. See
+their documentation for the types they expect.
