Added API change note and docs

jdollichon · jdollichon · commit ce9737d5286b · 2018-06-03T09:50:27.000+02:00
diff --git a/doc/api/next_api_changes/2018-06-03-JD-funcani-zorder.rst b/doc/api/next_api_changes/2018-06-03-JD-funcani-zorder.rst
@@ -0,0 +1,9 @@
+`.FuncAnimation` now draws artists according to their zorder when blitting
+--------------------------------------------------------------------------
+
+`.FuncAnimation` now draws artists returned by the user-
+function according to their zorder when using blitting,
+instead of using the order in which they are being passed.
+However, note that only zorder of passed artists will be
+respected, as they are drawn on top of any existing artists
+(see `#11369 <https://github.com/matplotlib/matplotlib/issues/11369>`_).
diff --git a/lib/matplotlib/animation.py b/lib/matplotlib/animation.py
@@ -1607,8 +1607,10 @@ def init_func() -> iterable_of_artists:
        of frames is completed.  Defaults to ``True``.
 
     blit : bool, optional
-       Controls whether blitting is used to optimize drawing.  Defaults
-       to ``False``.
+       Controls whether blitting is used to optimize drawing. Note: when using
+       blitting any animated artists will be drawn according to their zorder.
+       However, they will be drawn on top of any previous artists, regardless
+       of their zorder.  Defaults to ``False``.
 
     '''
     def __init__(self, fig, func, frames=None, init_func=None, fargs=None,
