From a77e5a8cbff7cd4789dd09a80f06ce65166c0a87 Mon Sep 17 00:00:00 2001
From: ijrsvt <ian.rodney@gmail.com>
Date: Mon, 27 Apr 2020 17:06:08 -0700
Subject: [PATCH] [Doc] Fix Docstring for Task Cancellation (#8198)

---
 doc/source/package-ref.rst |  2 ++
 python/ray/worker.py       | 23 +++++++++++++++++------
 2 files changed, 19 insertions(+), 6 deletions(-)

diff --git a/doc/source/package-ref.rst b/doc/source/package-ref.rst
index acd55eae5..463039823 100644
--- a/doc/source/package-ref.rst
+++ b/doc/source/package-ref.rst
@@ -15,6 +15,8 @@ Ray Package Reference
 
 .. autofunction:: ray.kill
 
+.. autofunction:: ray.cancel
+
 .. autofunction:: ray.get_gpu_ids
 
 .. autofunction:: ray.get_resource_ids
diff --git a/python/ray/worker.py b/python/ray/worker.py
index eac9e9072..6592dc178 100644
--- a/python/ray/worker.py
+++ b/python/ray/worker.py
@@ -1682,16 +1682,27 @@ def kill(actor):
 
 
 def cancel(object_id, force=False):
-    """Kill a task forcefully.
+    """Cancels a locally-submitted task according to the following conditions.
 
-    This will interrupt any running tasks on the actor, causing them to fail
-    immediately. Any atexit handlers installed in the actor will still be run.
+    If the specified task is pending execution, it will not be executed. If
+    the task is currently executing, the behavior depends on the ``force``
+    flag. When ``force=False``, a KeyboardInterrupt will be raised in Python
+    and when ``force=True``, the executing the task will immediately exit. If
+    the task is already finished, nothing will happen.
 
-    If this actor is reconstructable, it will be attempted to be reconstructed.
+    Only non-actor tasks can be canceled. Canceled tasks will not be
+    retried (max_retries will not be respected).
+
+    Calling ray.get on a canceled task will raise a RayCancellationError.
 
     Args:
-        id (ActorHandle or ObjectID): Handle for the actor to kill or ObjectID
-            of the task to kill.
+        object_id (ObjectID): ObjectID returned by the task
+            that should be canceled.
+        force (boolean): Whether to force-kill a running task by killing
+            the worker that is running the task.
+    Raises:
+        ValueError: This is also raised for actor tasks, already completed
+            tasks, and non-locally submitted tasks.
     """
     worker = ray.worker.global_worker
     worker.check_connected()