cleanups

Author: ktoso

stdlib/public/Concurrency/Task+TaskExecutor.swift

@@ -332,7 +332,7 @@ extension Task where Failure == Never {
   /// Runs the given nonthrowing operation asynchronously
   /// as part of a new top-level task.
   ///
-  /// Don't use a detached task if it's possible
+  /// Don't use a detached unstructured task if it's possible
   /// to model the operation using structured concurrency features like child tasks.
   /// Child tasks inherit the parent task's priority and task-local storage,
   /// and canceling a parent task automatically cancels all of its child tasks.
@@ -393,7 +393,7 @@ extension Task where Failure == Error {
   ///
   /// If the operation throws an error, this method propagates that error.
   ///
-  /// Don't use a detached task if it's possible
+  /// Don't use a detached unstructured task if it's possible
   /// to model the operation using structured concurrency features like child tasks.
   /// Child tasks inherit the parent task's priority and task-local storage,
   /// and canceling a parent task automatically cancels all of its child tasks.

stdlib/public/Concurrency/Task+init.swift.gyb

@@ -76,6 +76,12 @@ import Swift
 %   ARROW_RETURN_TYPE = '' # init does not spell out return type
 % end
 
+% if IS_DETACHED:
+%   THE_FUNC = 'public static func detached'
+% else:
+%   THE_FUNC = 'public init'
+% end
+
 % # ====================================================================================================================
 @available(SwiftStdlib 5.1, *)
 extension Task where Failure == ${FAILURE_TYPE} {
@@ -85,11 +91,7 @@ extension Task where Failure == ${FAILURE_TYPE} {
   @discardableResult
   @_alwaysEmitIntoClient
   @available(*, unavailable, message: "Unavailable in task-to-thread concurrency model")
-  % if IS_DETACHED:
-    public static func detached(
-  % else:
-    public init(
-  % end
+  ${THE_FUNC}(
       ${",\n    ".join(adjust_params_for_kind(PARAMS))}
     ) ${ARROW_RETURN_TYPE}{
     fatalError("Unavailable in task-to-thread concurrency model.")
@@ -100,11 +102,7 @@ extension Task where Failure == ${FAILURE_TYPE} {
   @discardableResult
   @_alwaysEmitIntoClient
   @available(SwiftStdlib 5.1, *)
-  % if IS_DETACHED:
-    public static func detached(
-  % else:
-    public init(
-  % end
+  ${THE_FUNC}(
       ${",\n    ".join(adjust_params_for_kind(PARAMS))}
     ) ${ARROW_RETURN_TYPE}{
     // Set up the job flags for a new task.
@@ -126,36 +124,53 @@ extension Task where Failure == ${FAILURE_TYPE} {
 
 % # --------------------------------------------------------------------------------------------------------------------
 #else
+% if IS_THROWING:
+  /// Runs the given throwing operation asynchronously
+% else:
   /// Runs the given nonthrowing operation asynchronously
-  /// as part of a new top-level task.
+% end
+% if IS_DETACHED:
+  /// as part of a new _unstructured_ _detached_ top-level task.
+% else:
+  /// as part of a new _unstructured_ top-level task.
+% end
+  ///
+% if IS_THROWING:
+  /// If the `operation` throws an error, it is caught by the `Task` and will be
+  /// rethrown only when the task's `value` is awaited. Take care to not accidentally
+  /// dismiss errors by not awaiting on the task's resulting value.
+% end
   ///
-  /// Don't use a detached task if it's possible
+% if IS_DETACHED:
+  /// Don't use a detached unstructured task if it's possible
   /// to model the operation using structured concurrency features like child tasks.
   /// Child tasks inherit the parent task's priority and task-local storage,
   /// and canceling a parent task automatically cancels all of its child tasks.
   /// You need to handle these considerations manually with a detached task.
+% end
   ///
-  /// You need to keep a reference to the detached task
+  /// You need to keep a reference to the task
   /// if you want to cancel it by calling the `Task.cancel()` method.
-  /// Discarding your reference to a detached task
+  /// Discarding your reference to a task
   /// doesn't implicitly cancel that task,
   /// it only makes it impossible for you to explicitly cancel the task.
   ///
   /// - Parameters:
   % if HAS_TASK_NAME:
   ///   - name: Human readable name of the task.
   % end
+  % if HAS_TASK_NAME:
+  ///   - taskExecutor: the preferred task executor for this task,
+  ///       and any child tasks created by it. Explicitly passing `nil` is
+  ///       interpreted as "no preference".
+  % end
   ///   - priority: The priority of the task.
   ///   - operation: The operation to perform.
   ///
   /// - Returns: A reference to the task.
   ${"\n  ".join(ALL_AVAILABILITY)}
   @discardableResult
-% if IS_DETACHED:
-  public static func detached(
-% else:
-  public init(
-% end
+  ${THE_FUNC}(
     ${",\n    ".join(adjust_params_for_kind(PARAMS))}
   ) ${ARROW_RETURN_TYPE}{
 

stdlib/public/Concurrency/Task.swift

@@ -724,7 +724,7 @@ extension Task where Failure == Never {
   /// Runs the given nonthrowing operation asynchronously
   /// as part of a new top-level task.
   ///
-  /// Don't use a detached task if it's possible
+  /// Don't use a detached unstructured task if it's possible
   /// to model the operation using structured concurrency features like child tasks.
   /// Child tasks inherit the parent task's priority and task-local storage,
   /// and canceling a parent task automatically cancels all of its child tasks.
@@ -784,9 +784,11 @@ extension Task where Failure == Error {
   /// Runs the given throwing operation asynchronously
   /// as part of a new top-level task.
   ///
-  /// If the operation throws an error, this method propagates that error.
+  /// If the `operation` throws an error, it is caught by the `Task` and will be
+  /// rethrown only when the task's `value` is awaited. Take care to not accidentally
+  /// dismiss errors by not awaiting on the task's resulting value.
   ///
-  /// Don't use a detached task if it's possible
+  /// Don't use a detached unstructured task if it's possible
   /// to model the operation using structured concurrency features like child tasks.
   /// Child tasks inherit the parent task's priority and task-local storage,
   /// and canceling a parent task automatically cancels all of its child tasks.