From 27c8ee1143415fd6dfd809204ccb4c88fda5690f Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Sat, 13 Oct 2018 19:16:22 +0200
Subject: [PATCH] Improve docstring of draw_idle()

---
 lib/matplotlib/backend_bases.py | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
index f7fb265437a9..c6cdb543434e 100644
--- 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():