Merge pull request swiftlang#37955 from amartini51/doc_comment_fixes

Doc comment fixes

Author: DougGregor

stdlib/public/Concurrency/AsyncIteratorProtocol.swift

@@ -12,7 +12,7 @@
 
 import Swift
 
-/// A type that that asychronously supplies the values of a sequence one at a
+/// A type that asynchronously supplies the values of a sequence one at a
 /// time.
 ///
 /// The `AsyncIteratorProtocol` defines the type returned by the

stdlib/public/Concurrency/AsyncSequence.swift

@@ -236,6 +236,8 @@ extension AsyncSequence {
   /// The predicate executes each time the asynchronous sequence produces an
   /// element, until either the predicate returns `false` or the sequence ends.
   ///
+  /// If the asynchronous sequence is empty, this method returns `true`.
+  ///
   /// - Parameter predicate: A closure that takes an element of the asynchronous
   ///   sequence as its argument and returns a Boolean value that indicates
   ///   whether the passed element satisfies a condition.

stdlib/public/Concurrency/AsyncThrowingPrefixWhileSequence.swift

@@ -43,7 +43,7 @@ extension AsyncSequence {
   ///     }
   ///     // Prints: 1  2  3  4  Error: MyError()
   ///
-  /// - Parameter isIncluded: A error-throwing closure that takes an element of
+  /// - Parameter predicate: A error-throwing closure that takes an element of
   ///   the asynchronous sequence as its argument and returns a Boolean value
   ///   that indicates whether to include the element in the modified sequence.
   /// - Returns: An asynchronous sequence that contains, in order, the elements

stdlib/public/Concurrency/CheckedContinuation.swift

@@ -259,7 +259,7 @@ extension CheckedContinuation {
 ///   - function: A string identifying the declaration that is the notional
 ///     source for the continuation, used to identify the continuation in
 ///     runtime diagnostics related to misuse of this continuation.
-///   - body: A closure that takes an `UnsafeContinuation` parameter.
+///   - body: A closure that takes a `CheckedContinuation` parameter.
 ///     You must resume the continuation exactly once.
 @available(SwiftStdlib 5.5, *)
 public func withCheckedContinuation<T>(

stdlib/public/Concurrency/PartialAsyncTask.swift

@@ -44,7 +44,7 @@ public struct UnownedJob {
 /// `resume(with:)`,
 /// or `resume()` method.
 ///
-/// - Important: You must call a resume methods exactly once
+/// - 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,
@@ -243,7 +243,7 @@ internal func _resumeUnsafeThrowingContinuationWithError<T>(
 #endif
 
 /// Suspends the current task,
-/// then calls the given closure with the an unsafe continuation for the current task.
+/// then calls the given closure with an unsafe continuation for the current task.
 ///
 /// - Parameter fn: A closure that takes an `UnsafeContinuation` parameter.
 /// You must resume the continuation exactly once.
@@ -260,7 +260,7 @@ public func withUnsafeContinuation<T>(
 }
 
 /// Suspends the current task,
-/// then calls the given closure with the an unsafe throwing continuation for 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.

stdlib/public/Concurrency/Task.swift

@@ -84,31 +84,17 @@ extension Task {
   /// If the awaited on task gets cancelled externally the `get()` will throw
   /// a cancellation error.
   ///
-  /// If the task gets cancelled internally, e.g. by checking for cancellation
-  /// and throwing a specific error or using `checkCancellation` the error
-  /// thrown out of the task will be re-thrown here.
+  /// If the task gets cancelled internally --
+  /// for example, by checking for cancellation
+  /// and throwing a specific error, or by calling `checkCancellation()`,
+  /// then the error thrown by the task is rethrown here.
   public var value: Success {
     get async throws {
       return try await _taskFutureGetThrowing(_task)
     }
   }
 
-  /// Wait for the task to complete, returning (or throwing) its result.
-  ///
-  /// ### Priority
-  /// If the task has not completed yet, its priority will be elevated to the
-  /// priority of the current task. Note that this may not be as effective as
-  /// creating the task with the "right" priority to in the first place.
-  ///
-  /// ### Cancellation
-  /// If the awaited on task gets cancelled externally the `get()` will throw
-  /// a cancellation error.
-  ///
-  /// If the task gets cancelled internally, e.g. by checking for cancellation
-  /// and throwing a specific error or using `checkCancellation` the error
-  /// thrown out of the task will be re-thrown here.
-
-  /// Wait for the task to complete, returning its `Result`.
+  /// Wait for the task to complete, returning its result.
   ///
   /// ### Priority
   /// If the task has not completed yet, its priority will be elevated to the
@@ -119,9 +105,10 @@ extension Task {
   /// If the awaited on task gets cancelled externally the `get()` will throw
   /// a cancellation error.
   ///
-  /// If the task gets cancelled internally, e.g. by checking for cancellation
-  /// and throwing a specific error or using `checkCancellation` the error
-  /// thrown out of the task will be re-thrown here.
+  /// If the task gets cancelled internally --
+  /// for example, by checking for cancellation
+  /// and throwing a specific error, or by calling `checkCancellation()`,
+  /// then the error thrown by the task is returned here.
   public var result: Result<Success, Failure> {
     get async {
       do {

stdlib/public/Concurrency/TaskGroup.swift

@@ -16,10 +16,10 @@ import Swift
 // ==== TaskGroup --------------------------------------------------------------
 
 /// Starts a new task group which provides a scope in which a dynamic number of
-/// tasks may be spawned.
+/// tasks may be created.
 ///
 /// When the group returns,
-/// it implicitly waits for all spawned tasks to complete.
+/// it implicitly waits for all child tasks to complete.
 /// The tasks are canceled only if `cancelAll()` was invoked before returning,
 /// if the group's task was canceled.
 ///
@@ -50,14 +50,14 @@ import Swift
 /// Canceling the task in which the group is running
 /// also cancels the group and all of its child tasks.
 ///
-/// If you call `spawn(priority:operation:)` to create a new task in a canceled group,
+/// If you call `async(priority:operation:)` to create a new task in a canceled group,
 /// that task is immediately canceled after creation.
-/// Alternatively, you can call `spawnUnlessCancelled(priority:operation:)`,
-/// which doesn't spawn the task if the group has already been canceled
+/// Alternatively, you can call `asyncUnlessCancelled(priority:operation:)`,
+/// which doesn't create the task if the group has already been canceled
 /// Choosing between these two functions
 /// lets you control how to react to cancellation within a group:
 /// some child tasks need to run regardless of cancellation
-/// and others are better not even being spawned
+/// and others are better not even being created
 /// knowing they can't produce useful results.
 ///
 /// Because the tasks you add to a group with this method are nonthrowing,
@@ -91,10 +91,10 @@ public func withTaskGroup<ChildTaskResult, GroupResult>(
   #endif
 }
 
-/// Starts a new scope in which a dynamic number of throwing tasks can be spawned.
+/// Starts a new scope in which a dynamic number of throwing tasks can be created.
 ///
 /// When the group returns,
-/// it implicitly waits for all spawned tasks to complete.
+/// it implicitly waits for all child tasks to complete.
 /// The tasks are canceled only if `cancelAll()` was invoked before returning,
 /// if the group's task was canceled,
 /// or if the group's body throws an error.
@@ -126,14 +126,14 @@ public func withTaskGroup<ChildTaskResult, GroupResult>(
 /// Canceling the task in which the group is running
 /// also cancels the group and all of its child tasks.
 ///
-/// If you call `spawn(priority:operation:)` to create a new task in a canceled group,
+/// If you call `async(priority:operation:)` to create a new task in a canceled group,
 /// that task is is immediately canceled after being created.
-/// Alternatively, you can call `spawnUnlessCancelled(priority:operation:)`,
-/// which doesn't spawn the task if the group has already been canceled
+/// Alternatively, you can call `asyncUnlessCancelled(priority:operation:)`,
+/// which doesn't create the task if the group has already been canceled
 /// Choosing between these two functions
 /// lets you control how to react to cancellation within a group:
 /// some child tasks need to run regardless of cancellation
-/// and others are better not even being spawned
+/// and others are better not even being created
 /// knowing they can't produce useful results.
 ///
 /// Throwing an error in one of the tasks of a task group
@@ -145,14 +145,14 @@ public func withTaskGroup<ChildTaskResult, GroupResult>(
 /// nothing is canceled and the group doesn't throw an error:
 ///
 ///     withThrowingTaskGroup { group in
-///         group.spawn { throw SomeError() }
+///         group.async { throw SomeError() }
 ///     }
 ///
 /// In contrast, this example throws `SomeError`
 /// and cancels all of the tasks in the group:
 ///
 ///     withThrowingTaskGroup { group in
-///         group.spawn { throw SomeError() }
+///         group.async { throw SomeError() }
 ///         try group.next()
 ///     }
 ///
@@ -194,7 +194,7 @@ public func withThrowingTaskGroup<ChildTaskResult, GroupResult>(
   #endif
 }
 
-/// A task group serves as storage for dynamically spawned child tasks.
+/// A task group serves as storage for dynamically created child tasks.
 ///
 /// To create a task group,
 /// call the `withTaskGroup(of:returning:body:)` method.
@@ -315,8 +315,8 @@ public struct TaskGroup<ChildTaskResult> {
   /// not in the order that those tasks were added to the task group.
   /// For example:
   ///
-  ///     group.spawn { 1 }
-  ///     group.spawn { 2 }
+  ///     group.async { 1 }
+  ///     group.async { 2 }
   ///
   ///     print(await group.next())
   ///     // Prints either "2" or "1".
@@ -424,7 +424,7 @@ public struct TaskGroup<ChildTaskResult> {
 // proofing, in case we'd ever have typed errors, however unlikely this may be.
 // Today the throwing task group failure is simply automatically bound to `Error`.
 
-/// A task group serves as storage for dynamically spawned,
+/// A task group serves as storage for dynamically created,
 /// potentially throwing, child tasks.
 ///
 @available(SwiftStdlib 5.5, *)
@@ -454,7 +454,7 @@ public struct ThrowingTaskGroup<ChildTaskResult, Failure: Error> {
     }
   }
 
-  /// Spawn, unconditionally, a child task in the group.
+  /// Unconditionally create a child task in the group.
   ///
   /// ### Error handling
   /// Operations are allowed to `throw`, in which case the `try await next()`
@@ -550,8 +550,8 @@ public struct ThrowingTaskGroup<ChildTaskResult, Failure: Error> {
   /// not in the order that those tasks were added to the task group.
   /// For example:
   ///
-  ///     group.spawn { 1 }
-  ///     group.spawn { 2 }
+  ///     group.async { 1 }
+  ///     group.async { 2 }
   ///
   ///     await print(group.next())
   ///     // Prints either "2" or "1".
@@ -610,8 +610,8 @@ public struct ThrowingTaskGroup<ChildTaskResult, Failure: Error> {
   /// not in the order that those tasks were added to the task group.
   /// For example:
   ///
-  ///     group.spawn { 1 }
-  ///     group.spawn { 2 }
+  ///     group.async { 1 }
+  ///     group.async { 2 }
   ///
   ///     guard let result = await group.nextResult() else {
   ///         return  // No task to wait on, which won't happen in this example.
@@ -710,9 +710,9 @@ extension TaskGroup: AsyncSequence {
   /// which you can use to continue iterating over the group's results.
   /// For example:
   ///
-  ///     group.spawn { 1 }
-  ///     group.spawn { throw SomeError }
-  ///     group.spawn { 2 }
+  ///     group.async { 1 }
+  ///     group.async { throw SomeError }
+  ///     group.async { 2 }
   ///     
   ///     do { 
   ///         // Assuming the child tasks complete in order, this prints "1"

stdlib/public/core/Collection.swift

@@ -1467,8 +1467,8 @@ extension Collection {
   ///     }
   ///     // Prints "[10, 20, 30, 40]"
   ///
-  /// - Parameter end: The index of the last element to include in the
-  ///   resulting subsequence. `end` must be a valid index of the collection
+  /// - Parameter position: The index of the last element to include in the
+  ///   resulting subsequence. `position` must be a valid index of the collection
   ///   that is not equal to the `endIndex` property.
   /// - Returns: A subsequence up to, and including, the `end` position.
   ///

stdlib/public/core/Policy.swift

@@ -74,7 +74,7 @@ public typealias Float64 = Double
 //===----------------------------------------------------------------------===//
 /// The default type for an otherwise-unconstrained integer literal.
 public typealias IntegerLiteralType = Int
-/// The default type for an otherwise-unconstrained floating point literal.
+/// The default type for an otherwise-unconstrained floating-point literal.
 public typealias FloatLiteralType = Double
 
 /// The default type for an otherwise-unconstrained Boolean literal.

stdlib/public/core/SequenceAlgorithms.swift

@@ -529,6 +529,8 @@ extension Sequence {
   ///     let allHaveAtLeastFive = names.allSatisfy({ $0.count >= 5 })
   ///     // allHaveAtLeastFive == true
   ///
+  /// If the sequence is empty, this method returns `true`.
+  ///
   /// - Parameter predicate: A closure that takes an element of the sequence
   ///   as its argument and returns a Boolean value that indicates whether
   ///   the passed element satisfies a condition.