Issue #24509: Clarify Handle.cancel() and loop.call_* methods.

1 files changed, 9 insertions, 3 deletions

diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
index c5a3385..33d3148 100644
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -97,7 +97,8 @@ keywords to your callback, use :func:`functools.partial`. For example,
    Any positional arguments after the callback will be passed to the
    callback when it is called.
 
-   An instance of :class:`asyncio.Handle` is returned.
+   An instance of :class:`asyncio.Handle` is returned, which can be
+   used to cancel the callback.
 
    :ref:`Use functools.partial to pass keywords to the callback
    <asyncio-pass-keywords>`.
@@ -130,7 +131,8 @@ a different clock than :func:`time.time`.
    Arrange for the *callback* to be called after the given *delay*
    seconds (either an int or float).
 
-   An instance of :class:`asyncio.Handle` is returned.
+   An instance of :class:`asyncio.Handle` is returned, which can be
+   used to cancel the callback.
 
    *callback* will be called exactly once per call to :meth:`call_later`.
    If two callbacks are scheduled for exactly the same time, it is
@@ -151,6 +153,9 @@ a different clock than :func:`time.time`.
 
    This method's behavior is the same as :meth:`call_later`.
 
+   An instance of :class:`asyncio.Handle` is returned, which can be
+   used to cancel the callback.
+
    :ref:`Use functools.partial to pass keywords to the callback
    <asyncio-pass-keywords>`.
 
@@ -704,7 +709,8 @@ Handle
 
    .. method:: cancel()
 
-      Cancel the call.
+      Cancel the call.  If the callback is already canceled or executed,
+      this method has no effect.
 
 
 Event loop examples