[3.12] Doc: Clarify the return type of Event.wait when timeout is used (GH-104168...

(cherry picked from commit 37f5d06b1bf830048c09ed967bb2cda945d56541)

Co-authored-by: Phil Elson <pelson.pub@gmail.com>

diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst
index 23d8cd158abd5d50fae7cfd37809c1fee1436474..25a738fc2e62fe440f98336021922a4616b67d0f 100644 (file)
--- a/Doc/library/threading.rst
+++ b/Doc/library/threading.rst
@@ -983,18 +983,15 @@ method.  The :meth:`~Event.wait` method blocks until the flag is true.
 
    .. method:: wait(timeout=None)
 
-      Block until the internal flag is true.  If the internal flag is true on
-      entry, return immediately.  Otherwise, block until another thread calls
-      :meth:`.set` to set the flag to true, or until the optional timeout occurs.
+      Block as long as the internal flag is false and the timeout, if given,
+      has not expired. The return value represents the
+      reason that this blocking method returned; ``True`` if returning because
+      the internal flag is set to true, or ``False`` if a timeout is given and
+      the the internal flag did not become true within the given wait time.
 
       When the timeout argument is present and not ``None``, it should be a
-      floating point number specifying a timeout for the operation in seconds
-      (or fractions thereof).
-
-      This method returns ``True`` if and only if the internal flag has been set to
-      true, either before the wait call or after the wait starts, so it will
-      always return ``True`` except if a timeout is given and the operation
-      times out.
+      floating point number specifying a timeout for the operation in seconds,
+      or fractions thereof.
 
       .. versionchanged:: 3.1
          Previously, the method always returned ``None``.