gh-132354: document return value for asyncio.Task.cancel

Doc/library/asyncio-task.rst

@@ -1381,7 +1381,11 @@ Task Object
 
       Request the Task to be cancelled.
 
-      This arranges for a :exc:`CancelledError` exception to be thrown
+      If the Task is already *done* or *cancelled*, return ``False``.
+      Otherwise, change the Task's state to *cancelled*,
+      schedule the callbacks, and return ``True``.
+
+      The method arranges for a :exc:`CancelledError` exception to be thrown
       into the wrapped coroutine on the next cycle of the event loop.
 
       The coroutine then has a chance to clean up or even deny the

Misc/ACKS

@@ -1662,6 +1662,7 @@ Andreas Schawo
 Neil Schemenauer
 David Scherer
 Wolfgang Scherer
+Felix Scherz
 Hynek Schlawack
 Bob Schmertz
 Gregor Schmid

Misc/NEWS.d/next/Documentation/2025-04-10-20-41-53.gh-issue-132354.GN6DcP.rst

@@ -0,0 +1 @@
+Document return value for :func:`asyncio.Task.cancel`.