Improve docstring and add comments

Author: ericpre

lib/matplotlib/tests/test_widgets.py

@@ -926,21 +926,27 @@ def test_span_selector_animated_artists_callback():
     (ln,) = ax.plot(x, values, animated=True)
     (ln2, ) = ax.plot([], animated=True)
 
+    # spin the event loop to let the backend process any pending operations
+    # before drawing artists
+    # See blitting tutorial
     plt.pause(0.1)
     ax.draw_artist(ln)
     fig.canvas.blit(fig.bbox)
 
     def mean(vmin, vmax):
+        # Return mean of values in x between *vmin* and *vmax*
         indmin, indmax = np.searchsorted(x, (vmin, vmax))
         v = values[indmin:indmax].mean()
-        print('here', x, v)
         ln2.set_data(x, v)
 
     span = widgets.SpanSelector(ax, mean, direction='horizontal',
                                 onmove_callback=mean,
                                 interactive=True,
                                 drag_from_anywhere=True,
                                 useblit=True)
+
+    # Add span selector and check that the line is draw after it was updated
+    # by the callback
     press_data = [1, 2]
     move_data = [2, 2]
     do_event(span, 'press', xdata=press_data[0], ydata=press_data[1], button=1)
@@ -952,6 +958,8 @@ def mean(vmin, vmax):
     span.update()
     assert ln2.stale is False
 
+    # Change span selector and check that the line is drawn/updated after its
+    # value was updated by the callback
     press_data = [4, 2]
     move_data = [5, 2]
     release_data = [5, 2]

lib/matplotlib/widgets.py

@@ -1841,12 +1841,15 @@ def set_active(self, active):
 
     def _get_animated_artists(self):
         """
-        Convenience method to get all animated artists of a figure, except
-        those already present in self.artists. 'z_order' is ignored.
-        """
-        return tuple([a for ax_ in self.ax.get_figure().get_axes()
-                      for a in ax_.get_children()
-                      if a.get_animated() and a not in self.artists])
+        Convenience method to get all animated artists of the figure containing
+        this widget, excluding those already present in self.artists.
+        The returned tuple is not sorted by 'z_order': z_order sorting is
+        valid only when considering all artists and not only a subset of all
+        artists.
+        """
+        return tuple(a for ax_ in self.ax.get_figure().get_axes()
+                     for a in ax_.get_children()
+                     if a.get_animated() and a not in self.artists)
 
     def update_background(self, event):
         """Force an update of the background."""