document cancellation in more depth on discarding group too

Author: ktoso

stdlib/public/Concurrency/DiscardingTaskGroup.swift

@@ -116,8 +116,11 @@ public func withDiscardingTaskGroup<GroupResult>(
 /// be the case with a ``TaskGroup``.
 ///
 /// ### Cancellation behavior
-/// A task group becomes cancelled in one of two ways: when ``cancelAll()`` is
-/// invoked on it, or when the ``Task`` running this task group is cancelled.
+/// A discarding task group becomes cancelled in one of the following ways:
+///
+/// - when ``cancelAll()`` is invoked on it,
+/// - when an error is thrown out of the `withThrowingDiscardingTaskGroup(...) { }` closure,
+/// - when the ``Task`` running this task group is cancelled.
 ///
 /// Since a `TaskGroup` is a structured concurrency primitive, cancellation is
 /// automatically propagated through all of its child-tasks (and their child
@@ -431,8 +434,28 @@ public func withThrowingDiscardingTaskGroup<GroupResult>(
 /// be the case with a ``TaskGroup``.
 ///
 /// ### Cancellation behavior
-/// A task group becomes cancelled in one of two ways: when ``cancelAll()`` is
-/// invoked on it, or when the ``Task`` running this task group is cancelled.
+/// A throwing discarding task group becomes cancelled in one of the following ways:
+///
+/// - when ``cancelAll()`` is invoked on it,
+/// - when an error is thrown out of the `withThrowingDiscardingTaskGroup(...) { }` closure,
+/// - when the ``Task`` running this task group is cancelled.
+///
+/// But also, and uniquely in *discarding* task groups:
+/// - when *any* of its child tasks throws.
+///
+/// The group becoming cancelled automatically, and cancelling all of its child tasks,
+/// 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 cancelled,
+/// 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
+/// operations submitted using `addTask`
+///
+/// Since a `TaskGroup` is a structured concurrency primitive, cancellation is
+/// automatically propagated through all of its child-tasks (and their child
+/// tasks).
 ///
 /// Since a `TaskGroup` is a structured concurrency primitive, cancellation is
 /// automatically propagated through all of its child-tasks (and their child
@@ -524,6 +547,7 @@ public struct ThrowingDiscardingTaskGroup<Failure: Error> {
 #endif
   }
 
+  ///
   public var isEmpty: Bool {
     _taskGroupIsEmpty(_group)
   }

stdlib/public/Concurrency/TaskGroup.swift

@@ -218,15 +218,12 @@ public func withThrowingTaskGroup<ChildTaskResult, GroupResult>(
 /// Tasks added to a task group execute concurrently, and may be scheduled in
 /// any order.
 ///
-/// ### Discarding behavior
-/// A discarding task group eagerly discards and releases its child tasks as
-/// soon as they complete. This allows for the efficient releasing of memory used
-/// by those tasks, which are not retained for future `next()` calls, as would
-/// be the case with a ``TaskGroup``.
-///
 /// ### Cancellation behavior
-/// A task group becomes cancelled in one of two ways: when ``cancelAll()`` is
-/// invoked on it, or when the ``Task`` running this task group is cancelled.
+/// A task group becomes cancelled in one of the following ways:
+///
+/// - when ``cancelAll()`` is invoked on it,
+/// - when an error is thrown out of the `withTaskGroup(...) { }` closure,
+/// - when the ``Task`` running this task group is cancelled.
 ///
 /// Since a `TaskGroup` is a structured concurrency primitive, cancellation is
 /// automatically propagated through all of its child-tasks (and their child
@@ -558,15 +555,12 @@ extension TaskGroup: Sendable { }
 /// Tasks added to a task group execute concurrently, and may be scheduled in
 /// any order.
 ///
-/// ### Discarding behavior
-/// A discarding task group eagerly discards and releases its child tasks as
-/// soon as they complete. This allows for the efficient releasing of memory used
-/// by those tasks, which are not retained for future `next()` calls, as would
-/// be the case with a ``TaskGroup``.
-///
 /// ### Cancellation behavior
-/// A task group becomes cancelled in one of two ways: when ``cancelAll()`` is
-/// invoked on it, or when the ``Task`` running this task group is cancelled.
+/// A task group becomes cancelled in one of the following ways:
+///
+/// - 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.
 ///
 /// Since a `TaskGroup` is a structured concurrency primitive, cancellation is
 /// automatically propagated through all of its child-tasks (and their child