[3.14] Clarify docs for scheduler.run(blocking=False) (GH-129575) (GH-150669)

(cherry picked from commit 2f8f569ba911ab3cff1356a15a3e688adc4ae917)

Co-authored-by: M. Greyson Christoforo <grey@christoforo.net>

diff --git a/Doc/library/sched.rst b/Doc/library/sched.rst
index 5560478ce15e28fc04e447c87ae0a9dc50f38e0a..302231d95f89791d8f55e105aadc5567b87edb68 100644 (file)
--- a/Doc/library/sched.rst
+++ b/Doc/library/sched.rst
@@ -119,9 +119,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