Clarify docs for scheduler.run(blocking=False) (GH-129575)

diff --git a/Doc/library/sched.rst b/Doc/library/sched.rst
index 70541c5f3cb3676fffb55e1b8e271bac4234f77a..037e27f031d0c826491600192589e3133c2d9b6f 100644 (file)
--- a/Doc/library/sched.rst
+++ b/Doc/library/sched.rst
@@ -117,9 +117,11 @@ Scheduler Objects
    function passed to the constructor) for the next event, then execute it and so
    on until there are no more scheduled events.
 
-   If *blocking* is false executes the scheduled events due to expire soonest
-   (if any) and then return the deadline of the next scheduled call in the
-   scheduler (if any).
+   If *blocking* is false, immediately executes all events in the queue which have
+   a time value less than or equal to the current *timefunc* value (if any) and
+   returns the difference between the current *timefunc* value and the time value
+   of the next scheduled event in the scheduler's event queue.  If the queue is
+   empty, returns ``None``.
 
    Either *action* or *delayfunc* can raise an exception.  In either case, the
    scheduler will maintain a consistent state and propagate the exception.  If an