Cherry pick Swift 5.5 doc changes in PartialAsyncTask.swift

Author: amartini51

stdlib/public/Concurrency/PartialAsyncTask.swift

@@ -19,7 +19,10 @@ import Swift
 internal func _swiftJobRun(_ job: UnownedJob,
                            _ executor: UnownedSerialExecutor) -> ()
 
-/// A job is a unit of scheduleable work.
+/// A unit of scheduleable work.
+///
+/// Unless you're implementing a scheduler,
+/// you don't generally interact with jobs directly.
 @available(SwiftStdlib 5.1, *)
 @frozen
 public struct UnownedJob: Sendable {
@@ -32,6 +35,38 @@ public struct UnownedJob: Sendable {
   }
 }
 
+/// A mechanism to interface
+/// between synchronous and asynchronous code,
+/// without correctness checking.
+///
+/// A *continuation* is an opaque representation of program state.
+/// To create a continuation in asynchronous code,
+/// call the `withUnsafeContinuation(_:)` or
+/// `withUnsafeThrowingContinuation(_:)` function.
+/// To resume the asynchronous task,
+/// call the `resume(returning:)`,
+/// `resume(throwing:)`,
+/// `resume(with:)`,
+/// or `resume()` method.
+///
+/// - Important: You must call a resume method exactly once
+///   on every execution path throughout the program.
+///   Resuming from a continuation more than once is undefined behavior.
+///   Never resuming leaves the task in a suspended state indefinitely,
+///   and leaks any associated resources.
+///
+/// `CheckedContinuation` performs runtime checks
+/// for missing or multiple resume operations.
+/// `UnsafeContinuation` avoids enforcing these invariants at runtime
+/// because it aims to be a low-overhead mechanism
+/// for interfacing Swift tasks with
+/// event loops, delegate methods, callbacks,
+/// and other non-`async` scheduling mechanisms.
+/// However, during development, the ability to verify that the
+/// invariants are being upheld in testing is important.
+/// Because both types have the same interface,
+/// you can replace one with the other in most circumstances,
+/// without making other changes.
 @available(SwiftStdlib 5.1, *)
 @frozen
 public struct UnsafeContinuation<T, E: Error>: Sendable {
@@ -42,18 +77,19 @@ public struct UnsafeContinuation<T, E: Error>: Sendable {
     self.context = context
   }
 
-  /// Resume the task awaiting the continuation by having it return normally
-  /// from its suspension point.
+  /// Resume the task that's awaiting the continuation
+  /// by returning the given value.
   ///
   /// - Parameter value: The value to return from the continuation.
   ///
-  /// A continuation must be resumed exactly once. If the continuation has
-  /// already been resumed through this object, then the attempt to resume
-  /// the continuation again will result in undefined behavior.
+  /// A continuation must be resumed exactly once.
+  /// If the continuation has already resumed,
+  /// then calling this method results in undefined behavior.
   ///
-  /// After `resume` enqueues the task, control is immediately returned to
-  /// the caller. The task will continue executing when its executor is
-  /// able to reschedule it.
+  /// After calling this method,
+  /// control immediately returns to the caller.
+  /// The task continues executing
+  /// when its executor schedules it.
   @_alwaysEmitIntoClient
   public func resume(returning value: __owned T) where E == Never {
     #if compiler(>=5.5) && $BuiltinContinuation
@@ -63,18 +99,19 @@ public struct UnsafeContinuation<T, E: Error>: Sendable {
     #endif
   }
 
-  /// Resume the task awaiting the continuation by having it return normally
-  /// from its suspension point.
+  /// Resume the task that's awaiting the continuation
+  /// by returning the given value.
   ///
   /// - Parameter value: The value to return from the continuation.
   ///
-  /// A continuation must be resumed exactly once. If the continuation has
-  /// already been resumed through this object, then the attempt to resume
-  /// the continuation again will result in undefined behavior.
+  /// A continuation must be resumed exactly once.
+  /// If the continuation has already resumed,
+  /// then calling this method results in undefined behavior.
   ///
-  /// After `resume` enqueues the task, control is immediately returned to
-  /// the caller. The task will continue executing when its executor is
-  /// able to reschedule it.
+  /// After calling this method,
+  /// control immediately returns to the caller.
+  /// The task continues executing
+  /// when its executor schedules it.
   @_alwaysEmitIntoClient
   public func resume(returning value: __owned T) {
     #if compiler(>=5.5) && $BuiltinContinuation
@@ -84,18 +121,19 @@ public struct UnsafeContinuation<T, E: Error>: Sendable {
     #endif
   }
 
-  /// Resume the task awaiting the continuation by having it throw an error
-  /// from its suspension point.
+  /// Resume the task that's awaiting the continuation
+  /// by throwing the given error.
   ///
   /// - Parameter error: The error to throw from the continuation.
   ///
-  /// A continuation must be resumed exactly once. If the continuation has
-  /// already been resumed through this object, then the attempt to resume
-  /// the continuation again will result in undefined behavior.
+  /// A continuation must be resumed exactly once.
+  /// If the continuation has already resumed,
+  /// then calling this method results in undefined behavior.
   ///
-  /// After `resume` enqueues the task, control is immediately returned to
-  /// the caller. The task will continue executing when its executor is
-  /// able to reschedule it.
+  /// After calling this method,
+  /// control immediately returns to the caller.
+  /// The task continues executing
+  /// when its executor schedules it.
   @_alwaysEmitIntoClient
   public func resume(throwing error: __owned E) {
 #if compiler(>=5.5) && $BuiltinContinuation
@@ -108,20 +146,22 @@ public struct UnsafeContinuation<T, E: Error>: Sendable {
 
 @available(SwiftStdlib 5.1, *)
 extension UnsafeContinuation {
-  /// Resume the task awaiting the continuation by having it either
-  /// return normally or throw an error based on the state of the given
-  /// `Result` value.
+  /// Resume the task that's awaiting the continuation
+  /// by returning or throwing the given result value.
   ///
-  /// - Parameter result: A value to either return or throw from the
-  ///   continuation.
+  /// - Parameter result: The result.
+  ///   If it contains a `.success` value,
+  ///   the continuation returns that value;
+  ///   otherwise, it throws the `.error` value.
   ///
-  /// A continuation must be resumed exactly once. If the continuation has
-  /// already been resumed through this object, then the attempt to resume
-  /// the continuation again will trap.
+  /// A continuation must be resumed exactly once.
+  /// If the continuation has already resumed,
+  /// then calling this method results in undefined behavior.
   ///
-  /// After `resume` enqueues the task, control is immediately returned to
-  /// the caller. The task will continue executing when its executor is
-  /// able to reschedule it.
+  /// After calling this method,
+  /// control immediately returns to the caller.
+  /// The task continues executing
+  /// when its executor schedules it.
   @_alwaysEmitIntoClient
   public func resume<Er: Error>(with result: Result<T, Er>) where E == Error {
     switch result {
@@ -132,20 +172,22 @@ extension UnsafeContinuation {
     }
   }
 
-  /// Resume the task awaiting the continuation by having it either
-  /// return normally or throw an error based on the state of the given
-  /// `Result` value.
+  /// Resume the task that's awaiting the continuation
+  /// by returning or throwing the given result value.
   ///
-  /// - Parameter result: A value to either return or throw from the
-  ///   continuation.
+  /// - Parameter result: The result.
+  ///   If it contains a `.success` value,
+  ///   the continuation returns that value;
+  ///   otherwise, it throws the `.error` value.
   ///
-  /// A continuation must be resumed exactly once. If the continuation has
-  /// already been resumed through this object, then the attempt to resume
-  /// the continuation again will trap.
+  /// A continuation must be resumed exactly once.
+  /// If the continuation has already resumed,
+  /// then calling this method results in undefined behavior.
   ///
-  /// After `resume` enqueues the task, control is immediately returned to
-  /// the caller. The task will continue executing when its executor is
-  /// able to reschedule it.
+  /// After calling this method,
+  /// control immediately returns to the caller.
+  /// The task continues executing
+  /// when its executor schedules it.
   @_alwaysEmitIntoClient
   public func resume(with result: Result<T, E>) {
     switch result {
@@ -156,16 +198,16 @@ extension UnsafeContinuation {
     }
   }
 
-  /// Resume the task awaiting the continuation by having it return normally
-  /// from its suspension point.
+  /// Resume the task that's awaiting the continuation by returning.
   ///
-  /// A continuation must be resumed exactly once. If the continuation has
-  /// already been resumed through this object, then the attempt to resume
-  /// the continuation again will trap.
+  /// A continuation must be resumed exactly once.
+  /// If the continuation has already resumed,
+  /// then calling this method results in undefined behavior.
   ///
-  /// After `resume` enqueues the task, control is immediately returned to
-  /// the caller. The task will continue executing when its executor is
-  /// able to reschedule it.
+  /// After calling this method,
+  /// control immediately returns to the caller.
+  /// The task continues executing
+  /// when its executor schedules it.
   @_alwaysEmitIntoClient
   public func resume() where T == Void {
     self.resume(returning: ())
@@ -204,9 +246,13 @@ internal func _resumeUnsafeThrowingContinuationWithError<T>(
 
 #endif
 
-/// The operation functions must resume the continuation *exactly once*.
+/// Suspends the current task,
+/// then calls the given closure with an unsafe continuation for the current task.
 ///
-/// The continuation will not begin executing until the operation function returns.
+/// - Parameter fn: A closure that takes an `UnsafeContinuation` parameter.
+/// You must resume the continuation exactly once.
+///
+/// - Returns: The value passed to the continuation by the closure.
 @available(SwiftStdlib 5.1, *)
 @_alwaysEmitIntoClient
 public func withUnsafeContinuation<T>(
@@ -217,9 +263,16 @@ public func withUnsafeContinuation<T>(
   }
 }
 
-/// The operation functions must resume the continuation *exactly once*.
+/// Suspends the current task,
+/// then calls the given closure with an unsafe throwing continuation for the current task.
+///
+/// - Parameter fn: A closure that takes an `UnsafeContinuation` parameter.
+/// You must resume the continuation exactly once.
+///
+/// - Returns: The value passed to the continuation by the closure.
 ///
-/// The continuation will not begin executing until the operation function returns.
+/// If `resume(throwing:)` is called on the continuation,
+/// this function throws that error.
 @available(SwiftStdlib 5.1, *)
 @_alwaysEmitIntoClient
 public func withUnsafeThrowingContinuation<T>(