Improve docstring of draw_idle()

timhoffm · timhoffm · commit 27c8ee114341 · 2018-10-14T21:53:56.000+02:00
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -1893,7 +1893,16 @@ def draw(self, *args, **kwargs):
 
     def draw_idle(self, *args, **kwargs):
         """
-        :meth:`draw` only if idle; defaults to draw but backends can override
+        Request a widget redraw once control returns to the GUI event loop.
+
+        Even if multiple calls to `draw_idle` occur before control returns
+        to the GUI event loop, the figure will only be rendered once.
+
+        Note
+        ----
+        Backends may choose to override the method and implement their own
+        strategy to prevent multiple renderings.
+
         """
         if not self._is_idle_drawing:
             with self._idle_draw_cntx():
