Merge pull request swiftlang#76508 from swiftlang/ktoso-patch-17

Author: ktoso

stdlib/public/Concurrency/Task.swift

@@ -194,19 +194,44 @@ extension Task {
     }
   }
 
-  /// Indicates that the task should stop running.
+  /// Cancels this task.
   ///
-  /// Task cancellation is cooperative:
-  /// a task that supports cancellation
-  /// checks whether it has been canceled at various points during its work.
+  /// Cancelling a task has three primary effects:
   ///
-  /// Calling this method on a task that doesn't support cancellation
-  /// has no effect.
-  /// Likewise, if the task has already run
-  /// past the last point where it would stop early,
-  /// calling this method has no effect.
+  /// - It flags the task as cancelled.
+  /// - It causes any active cancellation handlers on the task to run (once).
+  /// - It cancels any child tasks and task groups of the task, including
+  ///   those created in the future. If those tasks have cancellation handlers, 
+  ///   they also are triggered.
+  ///
+  /// Task cancellation is cooperative and idempotent.
+  ///
+  /// Cancelling a task does not automatically cause arbitrary functions on the task
+  /// to stop running or throw errors. A function _may_ choose to react
+  /// to cancellation by ending its work early, and it is conventional to
+  /// signal that to callers by throwing CancellationError. However,
+  /// a function that doesn't specifically check for cancellation will
+  /// run to completion normally even if the task it is running on is
+  /// cancelled. (Of course, it may still end early if it calls something
+  /// else that handles cancellation by throwing and then doesn't
+  /// handle the error.)
+  ///
+  /// It is safe to cancel a task from any task or thread. It is safe for
+  /// multiple tasks or threads to cancel the same task at the same
+  /// time. Cancelling a task that has already been cancelled has no
+  /// additional effect.
+  ///
+  /// `cancel` may need to acquire locks and synchronously run
+  /// arbitrary cancellation-handler code associated with the
+  /// cancelled task. To reduce the risk of deadlock, it is
+  /// recommended that callers release any locks they might be
+  /// holding before they call cancel.
+  ///
+  /// If the task has already run past the last point where it could have 
+  /// performed a cancellation check, cancelling it may have no observable effects.
   ///
   /// - SeeAlso: `Task.checkCancellation()`
+  /// - SeeAlso: `withTaskCancellationHandler(operation:onCancel:isolation:)`
   public func cancel() {
     Builtin.cancelAsyncTask(_task)
   }