Merge pull request #82894 from amartini51/fixup_pr_82558

Revise task group docs for style, fixing issues in the content changed in #82558 and some nearby content.

Author: amartini51

stdlib/public/Concurrency/DiscardingTaskGroup.swift

@@ -25,7 +25,7 @@ import Swift
 /// A group *always* waits for all of its child tasks
 /// to complete before it returns. Even canceled tasks must run until
 /// completion before this function returns.
-/// Cancelled child tasks cooperatively react to cancellation and attempt
+/// Canceled child tasks cooperatively react to cancellation and attempt
 /// to return as early as possible.
 /// After this function returns, the task group is always empty.
 ///
@@ -205,7 +205,7 @@ public struct DiscardingTaskGroup {
   /// If you add a task to a group after canceling the group,
   /// that task is canceled immediately after being added to the group.
   ///
-  /// Immediately  canceled  child tasks should therefore cooperatively check for and
+  /// Immediately canceled child tasks should therefore cooperatively check for and
   /// react  to cancellation, e.g. by throwing an `CancellationError` at their
   /// earliest convenience, or otherwise handling the cancellation.
   ///
@@ -427,7 +427,7 @@ public func _unsafeInheritExecutor_withThrowingDiscardingTaskGroup<GroupResult>(
 ///
 /// - when ``cancelAll()`` is invoked on it,
 /// - when an error is thrown out of the `withThrowingDiscardingTaskGroup { ... }` closure,
-/// - when the ``Task`` running this task group is  canceled .
+/// - when the ``Task`` running this task group is canceled.
 ///
 /// But also, and uniquely in *discarding* task groups:
 /// - when *any* of its child tasks throws.
@@ -436,7 +436,7 @@ public func _unsafeInheritExecutor_withThrowingDiscardingTaskGroup<GroupResult>(
 /// whenever *any* child task throws an error is a behavior unique to discarding task groups,
 /// because achieving such semantics is not possible otherwise, due to the missing `next()` method
 /// on discarding groups. Accumulating task groups can implement this by manually polling `next()`
-/// and deciding to `cancelAll()` when they decide an error should cause the group to become  canceled,
+/// and deciding to `cancelAll()` when they decide an error should cause the group to become canceled,
 /// however a discarding group cannot poll child tasks for results and therefore assumes that child
 /// task throws are an indication of a group wide failure. In order to avoid such behavior,
 /// use a ``DiscardingTaskGroup`` instead of a throwing one, or catch specific errors in
@@ -447,7 +447,7 @@ public func _unsafeInheritExecutor_withThrowingDiscardingTaskGroup<GroupResult>(
 /// tasks).
 ///
 /// A canceled task group can still keep adding tasks, however they will start
-/// being immediately  canceled, and may act accordingly to this. To avoid adding
+/// being immediately canceled, and may act accordingly to this. To avoid adding
 /// new tasks to an already canceled task group, use ``addTaskUnlessCancelled(priority:body:)``
 /// rather than the plain ``addTask(priority:body:)`` which adds tasks unconditionally.
 ///

stdlib/public/Concurrency/TaskCancellation.swift

@@ -39,13 +39,13 @@ import Swift
 /// ### Execution order and semantics
 /// The `operation` closure is always invoked, even when the
 /// `withTaskCancellationHandler(operation:onCancel:)` method is called from a task
-/// that was already cancelled.
+/// that was already canceled.
 ///
 /// When `withTaskCancellationHandler(operation:onCancel:)` is used in a task that has already been
-/// cancelled, the cancellation handler will be executed
+/// canceled, the cancellation handler will be executed
 /// immediately before the `operation` closure gets to execute.
 ///
-/// This allows the cancellation handler to set some external "cancelled" flag
+/// This allows the cancellation handler to set some external "canceled" flag
 /// that the operation may be *atomically* checking for in order to avoid
 /// performing any actual work once the operation gets to run.
 ///

stdlib/public/Concurrency/TaskGroup.swift

@@ -17,9 +17,9 @@ import Swift
 /// Starts a new scope that can contain a dynamic number of child tasks.
 ///
 /// A group *always* waits for all of its child tasks
-/// to complete before it returns. Even cancelled tasks must run until
+/// to complete before it returns. Even canceled tasks must run until
 /// completion before this function returns.
-/// Cancelled child tasks cooperatively react to cancellation and attempt
+/// Canceled child tasks cooperatively react to cancellation and attempt
 /// to return as early as possible.
 /// After this function returns, the task group is always empty.
 ///
@@ -265,29 +265,26 @@ public func _unsafeInheritExecutor_withThrowingTaskGroup<ChildTaskResult, GroupR
 /// Structured Concurrency
 /// ======================
 ///
+/// Structured concurrency is a way to organize your program, and tasks, in such a way that
+/// tasks don't outlive the scope in which they are created. Within a structured task hierarchy,
+/// no child task remains running longer than its parent task. This guarantee simplifies reasoning about resource usage,
+/// and is a powerful mechanism that you can use to write well-behaved concurrent programs.
+///
 /// A task group is the primary way to create structured concurrency tasks in Swift.
-/// Another way of creating structured tasks are `async let` declarations.
+/// Another way of creating structured tasks is an `async let` declaration.
 ///
 /// Structured concurrency tasks are often called "child tasks" because of their relationship with their parent task.
-/// A child task will inherit the parent's priority, task-local values, and will be structured in the sense that its
-/// lifetime will never exceed the lifetime of the parent task.
-///
-/// A child task inherits the parent's priority, task-local values, and will be structured in the sense that its
+/// A child task inherits the parent's priority, task-local values, and is structured in the sense that its
 /// lifetime never exceeds the lifetime of the parent task.
 ///
 /// A task group *always* waits for all child tasks to complete before it's destroyed.
 /// Specifically, `with...TaskGroup` APIs don't return until all the child tasks
 /// created in the group's scope have completed running.
 ///
-/// Structured concurrency is a way to organize your program, and tasks, in such a way that
-/// tasks don't outlive the scope in which they are created. Within a structured task hierarchy,
-/// no child task will remains running longer than its parent task. This simplifies reasoning about resource usage,
-/// and is a powerful mechanism that you can use to write well-behaved concurrent programs.
-///
-/// Structured Concurrency APIs (including task groups and `async let`), will *always* await the
+/// Structured concurrency APIs (including task groups and `async let`), *always* waits for the
 /// completion of tasks contained within their scope before returning. Specifically, this means that
-/// even if one were to await a single task result and return it from a `withTaskGroup` function body,
-/// the group will automatically await all the remaining tasks before returning:
+/// even if you await a single task result and return it from a `withTaskGroup` function body,
+/// the group automatically waits for all the remaining tasks before returning:
 ///
 ///     func takeFirst(actions: [@Sendable () -> Int]) async -> Int? {
 ///         await withTaskGroup { group in
@@ -300,7 +297,7 @@ public func _unsafeInheritExecutor_withThrowingTaskGroup<ChildTaskResult, GroupR
 ///     }
 ///
 /// In the above example, even though the code returns the first collected integer from all actions added to the task group,
-/// the task group will *always*, automatically, waits for the completion of all the resulting tasks.
+/// the task group *always*, automatically, waits for the completion of all the resulting tasks.
 ///
 /// You can use `group.cancelAll()` to signal cancellation to the remaining in-progress tasks,
 /// however this doesn't interrupt their execution automatically.
@@ -326,7 +323,7 @@ public func _unsafeInheritExecutor_withThrowingTaskGroup<ChildTaskResult, GroupR
 /// but other tasks are better not even being created
 /// when you know they can't produce useful results.
 ///
-/// In non-throwing task groups the tasks you add to a group with this method are nonthrowing,
+/// In nonthrowing task groups the tasks you add to a group with this method are nonthrowing,
 /// those tasks can't respond to cancellation by throwing `CancellationError`.
 /// The tasks must handle cancellation in some other way,
 /// such as returning the work completed so far, returning an empty result, or returning `nil`.
@@ -339,17 +336,18 @@ public func _unsafeInheritExecutor_withThrowingTaskGroup<ChildTaskResult, GroupR
 /// any order.
 ///
 /// ### Cancellation behavior
+///
 /// A task group becomes canceled in one of the following ways:
 ///
-/// - when ``cancelAll()`` is invoked on it,
-/// - when the ``Task`` running this task group is cancelled.
+/// - When ``cancelAll()`` is invoked on it.
+/// - When the ``Task`` running this task group is canceled.
 ///
-/// Since a `TaskGroup` is a structured concurrency primitive, cancellation is
+/// Because a `TaskGroup` is a structured concurrency primitive, cancellation is
 /// automatically propagated through all of its child-tasks (and their child
 /// tasks).
 ///
 /// A canceled task group can still keep adding tasks, however they will start
-/// being immediately cancelled, and may act accordingly to this. To avoid adding
+/// being immediately canceled, and might respond accordingly. To avoid adding
 /// new tasks to an already canceled task group, use ``addTaskUnlessCancelled(name:priority:body:)``
 /// rather than the plain ``addTask(name:priority:body:)`` which adds tasks unconditionally.
 ///
@@ -551,14 +549,14 @@ extension TaskGroup: Sendable { }
 ///
 /// - when ``cancelAll()`` is invoked on it,
 /// - when an error is thrown out of the `withThrowingTaskGroup(...) { }` closure,
-/// - when the ``Task`` running this task group is cancelled.
+/// - when the ``Task`` running this task group is canceled.
 ///
 /// Since a `ThrowingTaskGroup` is a structured concurrency primitive, cancellation is
 /// automatically propagated through all of its child-tasks (and their child
 /// tasks).
 ///
 /// A canceled task group can still keep adding tasks, however they will start
-/// being immediately cancelled, and may act accordingly to this. To avoid adding
+/// being immediately canceled, and may act accordingly to this. To avoid adding
 /// new tasks to an already canceled task group, use ``addTaskUnlessCancelled(priority:body:)``
 /// rather than the plain ``addTask(priority:body:)`` which adds tasks unconditionally.
 ///
@@ -616,7 +614,7 @@ public struct ThrowingTaskGroup<ChildTaskResult: Sendable, Failure: Error> {
   /// Wait for all of the group's remaining tasks to complete.
   ///
   /// If any of the tasks throw, the *first* error thrown is captured
-  /// and re-thrown by this method although the task group is *not* cancelled
+  /// and re-thrown by this method although the task group is *not* canceled
   /// when this happens.
   ///
   /// ### Cancelling the task group on first error

stdlib/public/Concurrency/TaskSleepDuration.swift

@@ -209,7 +209,7 @@ extension Task where Success == Never, Failure == Never {
 
   /// Suspends the current task for the given duration.
   ///
-  /// If the task is cancelled before the time ends, this function throws
+  /// If the task is canceled before the time ends, this function throws
   /// `CancellationError`.
   ///
   /// This function doesn't block the underlying thread.