[Python-checkins] gh-102810 Improve the sphinx docs for `asyncio.Timeout` (GH-102934)

[miss-islington]

https://github.com/python/cpython/commit/84ae50c9146e98be28cf3af4606f0ebad07807aa
commit: 84ae50c9146e98be28cf3af4606f0ebad07807aa
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2023-03-23T09:52:43-07:00
summary:

gh-102810 Improve the sphinx docs for `asyncio.Timeout` (GH-102934)

(cherry picked from commit f13fdacadfca87c71130057b6f03c89ae640c9b2)

Co-authored-by: JosephSBoyle <48555120+JosephSBoyle at users.noreply.github.com>
Co-authored-by: Alex Waygood <Alex.Waygood at Gmail.com>

files:
M Doc/library/asyncio-task.rst

diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
index 5fb8776c3db3..1e0a69c75e25 100644
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -624,32 +624,26 @@ Timeouts
     The context manager produced by :func:`asyncio.timeout` can be
     rescheduled to a different deadline and inspected.
 
-    .. class:: Timeout()
+    .. class:: Timeout(when)
 
        An :ref:`asynchronous context manager <async-context-managers>`
-       that limits time spent inside of it.
+       for cancelling overdue coroutines.
 
-        .. versionadded:: 3.11
+       ``when`` should be an absolute time at which the context should time out,
+       as measured by the event loop's clock:
+
+       - If ``when`` is ``None``, the timeout will never trigger.
+       - If ``when < loop.time()``, the timeout will trigger on the next
+         iteration of the event loop.
 
         .. method:: when() -> float | None
 
            Return the current deadline, or ``None`` if the current
            deadline is not set.
 
-           The deadline is a float, consistent with the time returned by
-           :meth:`loop.time`.
-
         .. method:: reschedule(when: float | None)
 
-            Change the time the timeout will trigger.
-
-            If *when* is ``None``, any current deadline will be removed, and the
-            context manager will wait indefinitely.
-
-            If *when* is a float, it is set as the new deadline.
-
-            if *when* is in the past, the timeout will trigger on the next
-            iteration of the event loop.
+            Reschedule the timeout.
 
         .. method:: expired() -> bool