Provide doc comments for AsyncSequence and related types (#37383)

* First draft docs for iterator, sequence type.

Also drop(while:), to get a feel for the AsyncSequence->AsyncSequence cases.

* Source docs for contains and reduce.

* Docs for methods in AsyncSequence.

This covers all the methods that return a single value. Still working on the extension methods that return new sequences.

* Early source docs for dropFirst(_:) and its type

* Correct doc format for dropFirst(_:).

* Prefix, plus some fixes.

* Docs for prefix(while:).

* Apply Philippe's snippet fixes.

* First draft docs on the map sequences.

Plus miscellaneous fixes throughout.

* Show result of flatMap example.

* More explicit cancellation guidance.

* Convert snippets to trailing closures.

* Correct misplaced doc comments.

* Apply suggestions from code review

Co-authored-by: Philippe Hausler <phausler@apple.com>

* Apply editorial feedback.

* Apply additional editorial feedback.

* Apply suggestions from code review

Co-authored-by: bjlanier <blanier@apple.com>

* Apply further editorial feedback.

Co-authored-by: Chris Adamson <cadamson@apple.com>
Co-authored-by: Philippe Hausler <phausler@apple.com>
Co-authored-by: bjlanier <blanier@apple.com>

Author: 4 people

stdlib/public/Concurrency/AsyncCompactMapSequence.swift

@@ -14,6 +14,37 @@ import Swift
 
 @available(SwiftStdlib 5.5, *)
 extension AsyncSequence {
+  /// Creates an asynchronous sequence that maps the given closure over the
+  /// asynchronous sequence’s elements, omitting results that don't return a
+  /// value.
+  ///
+  /// Use the `compactMap(_:)` method to transform every element received from
+  /// a base asynchronous sequence, while also discarding any `nil` results
+  /// from the closure. Typically, you use this to transform from one type of
+  /// element to another.
+  ///
+  /// In this example, an asynchronous sequence called `Counter` produces `Int`
+  /// values from `1` to `5`. The closure provided to the `compactMap(_:)`
+  /// method takes each `Int` and looks up a corresponding `String` from a
+  /// `romanNumeralDict` dictionary. Because there is no key for `4`, the closure
+  /// returns `nil` in this case, which `compactMap(_:)` omits from the
+  /// transformed asynchronous sequence.
+  ///
+  ///     let romanNumeralDict: [Int : String] =
+  ///         [1: "I", 2: "II", 3: "III", 5: "V"]
+  ///         
+  ///     let stream = Counter(howHigh: 5)
+  ///         .compactMap { romanNumeralDict[$0] }
+  ///     for await numeral in stream {
+  ///         print("\(numeral) ", terminator: " ")
+  ///     }
+  ///     // Prints: I  II  III  V
+  ///
+  /// - Parameter transform: A mapping closure. `transform` accepts an element
+  ///   of this sequence as its parameter and returns a transformed value of the
+  ///   same or of a different type.
+  /// - Returns: An asynchronous sequence that contains, in order, the
+  ///   non-`nil` elements produced by the `transform` closure.
   @inlinable
   public __consuming func compactMap<ElementOfResult>(
     _ transform: @escaping (Element) async -> ElementOfResult?
@@ -22,6 +53,8 @@ extension AsyncSequence {
   }
 }
 
+/// An asynchronous sequence that maps a given closure over the asynchronous
+/// sequence’s elements, omitting results that don't return a value.
 @available(SwiftStdlib 5.5, *)
 public struct AsyncCompactMapSequence<Base: AsyncSequence, ElementOfResult> {
   @usableFromInline
@@ -42,9 +75,15 @@ public struct AsyncCompactMapSequence<Base: AsyncSequence, ElementOfResult> {
 
 @available(SwiftStdlib 5.5, *)
 extension AsyncCompactMapSequence: AsyncSequence {
+  /// The type of element produced by this asynchronous sequence.
+  ///
+  /// The compact map sequence produces whatever type of element its
+  /// transforming closure produces.
   public typealias Element = ElementOfResult
+  /// The type of iterator that produces elements of the sequence.
   public typealias AsyncIterator = Iterator
 
+  /// The iterator that produces elements of the compact map sequence.
   public struct Iterator: AsyncIteratorProtocol {
     public typealias Element = ElementOfResult
 
@@ -63,6 +102,14 @@ extension AsyncCompactMapSequence: AsyncSequence {
       self.transform = transform
     }
 
+    /// Produces the next element in the compact map sequence.
+    ///
+    /// This iterator calls `next()` on its base iterator; if this call returns
+    /// `nil`, `next()` returns `nil`. Otherwise, `next()` calls the
+    /// transforming closure on the received element, returning it if the
+    /// transform returns a non-`nil` value. If the transform returns `nil`,
+    /// this method continues to wait for further elements until it gets one
+    /// that transforms to a non-`nil` value.
     @inlinable
     public mutating func next() async rethrows -> ElementOfResult? {
       while true {

stdlib/public/Concurrency/AsyncDropFirstSequence.swift

@@ -14,6 +14,28 @@ import Swift
 
 @available(SwiftStdlib 5.5, *)
 extension AsyncSequence {
+  /// Omits a specified number of elements from the base asynchronous sequence,
+  /// then passes through all remaining elements.
+  ///
+  /// Use `dropFirst(_:)` when you want to drop the first *n* elements from the
+  /// base sequence and pass through the remaining elements.
+  ///
+  /// In this example, an asynchronous sequence called `Counter` produces `Int`
+  /// values from `1` to `10`. The `dropFirst(_:)` method causes the modified
+  /// sequence to ignore the values `0` through `4`, and instead emit `5` through `10`:
+  ///
+  ///     for await number in Counter(howHigh: 10).dropFirst(3) {
+  ///         print("\(number) ", terminator: " ")
+  ///     }
+  ///     // prints "4 5 6 7 8 9 10"
+  ///
+  /// If the number of elements to drop exceeds the number of elements in the
+  /// sequence, the result is an empty sequence.
+  ///
+  /// - Parameter count: The number of elements to drop from the beginning of
+  ///   the sequence. `count` must be greater than or equal to zero.
+  /// - Returns: An asynchronous sequence that drops the first `count`
+  ///   elements from the base sequence.
   @inlinable
   public __consuming func dropFirst(
     _ count: Int = 1
@@ -24,6 +46,8 @@ extension AsyncSequence {
   }
 }
 
+/// An asynchronous sequence which omits a specified number of elements from the
+/// base asynchronous sequence, then passes through all remaining elements.
 @available(SwiftStdlib 5.5, *)
 public struct AsyncDropFirstSequence<Base: AsyncSequence> {
   @usableFromInline
@@ -41,9 +65,15 @@ public struct AsyncDropFirstSequence<Base: AsyncSequence> {
 
 @available(SwiftStdlib 5.5, *)
 extension AsyncDropFirstSequence: AsyncSequence {
+  /// The type of element produced by this asynchronous sequence.
+  ///
+  /// The drop-first sequence produces whatever type of element its base
+  /// iterator produces.
   public typealias Element = Base.Element
+  /// The type of iterator that produces elements of the sequence.
   public typealias AsyncIterator = Iterator
 
+  /// The iterator that produces elements of the drop-first sequence.
   public struct Iterator: AsyncIteratorProtocol {
     @usableFromInline
     var baseIterator: Base.AsyncIterator
@@ -57,6 +87,14 @@ extension AsyncDropFirstSequence: AsyncSequence {
       self.count = count
     }
 
+    /// Produces the next element in the drop-first sequence.
+    ///
+    /// Until reaching the number of elements to drop, this iterator calls
+    /// `next()` on its base iterator and discards the result. If the base
+    /// iterator returns `nil`, indicating the end of the sequence, this
+    /// iterator returns `nil`. After reaching the number of elements to
+    /// drop, this iterator passes along the result of calling `next()` on
+    /// the base iterator.
     @inlinable
     public mutating func next() async rethrows -> Base.Element? {
       var remainingToDrop = count
@@ -80,6 +118,12 @@ extension AsyncDropFirstSequence: AsyncSequence {
 
 @available(SwiftStdlib 5.5, *)
 extension AsyncDropFirstSequence {
+  /// Omits a specified number of elements from the base asynchronous sequence,
+  /// then passes through all remaining elements.
+  ///
+  /// When you call `dropFirst(_:)` on an asynchronous sequence that is already
+  /// an `AsyncDropFirstSequence`, the returned sequence simply adds the new
+  /// drop count to the current drop count.
   @inlinable
   public __consuming func dropFirst(
     _ count: Int = 1
@@ -91,4 +135,3 @@ extension AsyncDropFirstSequence {
     return AsyncDropFirstSequence(base, dropping: self.count + count)
   }
 }
-

stdlib/public/Concurrency/AsyncDropWhileSequence.swift

@@ -14,6 +14,33 @@ import Swift
 
 @available(SwiftStdlib 5.5, *)
 extension AsyncSequence {
+  /// Omits elements from the base asynchronous sequence until a given closure
+  /// returns false, after which it passes through all remaining elements.
+  ///
+  /// Use `drop(while:)` to omit elements from an asynchronous sequence until
+  /// the element received meets a condition you specify.
+  ///
+  /// In this example, an asynchronous sequence called `Counter` produces `Int`
+  /// values from `1` to `10`. The `drop(while:)` method causes the modified
+  /// sequence to ignore received values until it encounters one that is
+  /// divisible by `3`:
+  ///
+  ///     let stream = Counter(howHigh: 10)
+  ///         .drop { $0 % 3 != 0 }
+  ///     for await number in stream {
+  ///         print("\(number) ", terminator: " ")
+  ///     }
+  ///     // prints "3 4 5 6 7 8 9 10"
+  ///
+  /// After the predicate returns `false`, the sequence never executes it again,
+  /// and from then on the sequence passes through elements from its underlying
+  /// sequence as-is.
+  ///
+  /// - Parameter predicate: A closure that takes an element as a parameter and
+  ///   returns a Boolean value indicating whether to drop the element from the
+  ///   modified sequence.
+  /// - Returns: An asynchronous sequence that skips over values from the
+  ///   base sequence until the provided closure returns `false`.
   @inlinable
   public __consuming func drop(
     while predicate: @escaping (Element) async -> Bool
@@ -22,6 +49,9 @@ extension AsyncSequence {
   }
 }
 
+/// An asynchronous sequence which omits elements from the base sequence until a
+/// given closure returns false, after which it passes through all remaining
+/// elements.
 @available(SwiftStdlib 5.5, *)
 public struct AsyncDropWhileSequence<Base: AsyncSequence> {
   @usableFromInline
@@ -42,9 +72,16 @@ public struct AsyncDropWhileSequence<Base: AsyncSequence> {
 
 @available(SwiftStdlib 5.5, *)
 extension AsyncDropWhileSequence: AsyncSequence {
+  
+  /// The type of element produced by this asynchronous sequence.
+  ///
+  /// The drop-while sequence produces whatever type of element its base
+  /// sequence produces.
   public typealias Element = Base.Element
+  /// The type of iterator that produces elements of the sequence.
   public typealias AsyncIterator = Iterator
 
+  /// The iterator that produces elements of the drop-while sequence.
   public struct Iterator: AsyncIteratorProtocol {
     @usableFromInline
     var baseIterator: Base.AsyncIterator
@@ -61,6 +98,14 @@ extension AsyncDropWhileSequence: AsyncSequence {
       self.predicate = predicate
     }
 
+    /// Produces the next element in the drop-while sequence.
+    ///
+    /// This iterator calls `next()` on its base iterator and evaluates the
+    /// result with the `predicate` closure. As long as the predicate returns
+    /// `true`, this method returns `nil`. After the predicate returns `false`,
+    /// for a value received from the base iterator, this method returns that
+    /// value. After that, the iterator returns values received from its
+    /// base iterator as-is, and never executes the predicate closure again.
     @inlinable
     public mutating func next() async rethrows -> Base.Element? {
       while let predicate = self.predicate {
@@ -76,6 +121,7 @@ extension AsyncDropWhileSequence: AsyncSequence {
     }
   }
 
+  /// Creates an instance of the drop-while sequence iterator.
   @inlinable
   public __consuming func makeAsyncIterator() -> Iterator {
     return Iterator(base.makeAsyncIterator(), predicate: predicate)

stdlib/public/Concurrency/AsyncFilterSequence.swift

@@ -14,6 +14,25 @@ import Swift
 
 @available(SwiftStdlib 5.5, *)
 extension AsyncSequence {
+  /// Creates an asynchronous sequence that contains, in order, the elements of
+  /// the base sequence that satisfy the given predicate.
+  ///
+  /// In this example, an asynchronous sequence called `Counter` produces `Int`
+  /// values from `1` to `10`. The `filter(_:)` method returns `true` for even
+  /// values and `false` for odd values, thereby filtering out the odd values:
+  ///
+  ///     let stream = Counter(howHigh: 10)
+  ///         .filter { $0 % 2 == 0 }
+  ///     for await number in stream {
+  ///         print("\(number) ", terminator: " ")
+  ///     }
+  ///     // Prints: 2  4  6  8  10
+  ///
+  /// - Parameter isIncluded: A 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 filtered sequence.
+  /// - Returns: An asynchronous sequence that contains, in order, the elements
+  ///   of the base sequence that satisfy the given predicate.
   @inlinable
   public __consuming func filter(
     _ isIncluded: @escaping (Element) async -> Bool
@@ -22,6 +41,8 @@ extension AsyncSequence {
   }
 }
 
+/// An asynchronous sequence that contains, in order, the elements of
+/// the base sequence that satisfy a given predicate.
 @available(SwiftStdlib 5.5, *)
 public struct AsyncFilterSequence<Base: AsyncSequence> {
   @usableFromInline
@@ -42,9 +63,15 @@ public struct AsyncFilterSequence<Base: AsyncSequence> {
 
 @available(SwiftStdlib 5.5, *)
 extension AsyncFilterSequence: AsyncSequence {
+  /// The type of element produced by this asynchronous sequence.
+  ///
+  /// The filter sequence produces whatever type of element its base
+  /// sequence produces.
   public typealias Element = Base.Element
+  /// The type of iterator that produces elements of the sequence.
   public typealias AsyncIterator = Iterator
 
+  /// The iterator that produces elements of the filter sequence.
   public struct Iterator: AsyncIteratorProtocol {
     @usableFromInline
     var baseIterator: Base.AsyncIterator
@@ -61,6 +88,13 @@ extension AsyncFilterSequence: AsyncSequence {
       self.isIncluded = isIncluded
     }
 
+    /// Produces the next element in the filter sequence.
+    ///
+    /// This iterator calls `next()` on its base iterator; if this call returns
+    /// `nil`, `next()` returns nil. Otherwise, `next()` evaluates the
+    /// result with the `predicate` closure. If the closure returns `true`,
+    /// `next()` returns the received element; otherwise it awaits the next
+    /// element from the base iterator.
     @inlinable
     public mutating func next() async rethrows -> Base.Element? {
       while true {

stdlib/public/Concurrency/AsyncFlatMapSequence.swift

@@ -14,14 +14,41 @@ import Swift
 
 @available(SwiftStdlib 5.5, *)
 extension AsyncSequence {
-  @inlinable
+  /// Creates an asynchronous sequence that concatenates the results of calling
+  /// the given transformation with each element of this sequence.
+  ///
+  /// Use this method to receive a single-level asynchronous sequence when your
+  /// transformation produces an asynchronous sequence for each element.
+  ///
+  /// In this example, an asynchronous sequence called `Counter` produces `Int`
+  /// values from `1` to `5`. The transforming closure takes the received `Int`
+  /// and returns a new `Counter` that counts that high. For example, when the
+  /// transform receives `3` from the base sequence, it creates a new `Counter`
+  /// that produces the values `1`, `2`, and `3`. The `flatMap(_:)` method
+  /// "flattens" the resulting sequence-of-sequences into a single
+  /// `AsyncSequence`.
+  ///
+  ///     let stream = Counter(howHigh: 5)
+  ///         .flatMap { Counter(howHigh: $0) }
+  ///     for await number in stream {
+  ///         print("\(number)", terminator: " ")
+  ///     }
+  ///     // Prints: 1 1 2 1 2 3 1 2 3 4 1 2 3 4 5
+  ///
+  /// - Parameter transform: A mapping closure. `transform` accepts an element
+  ///   of this sequence as its parameter and returns an `AsyncSequence`.
+  /// - Returns: A single, flattened asynchronous sequence that contains all
+  ///   elements in all the asychronous sequences produced by `transform`.
+ @inlinable
   public __consuming func flatMap<SegmentOfResult: AsyncSequence>(
     _ transform: @escaping (Element) async -> SegmentOfResult
   ) -> AsyncFlatMapSequence<Self, SegmentOfResult> {
     return AsyncFlatMapSequence(self, transform: transform)
   }
 }
 
+/// An asynchronous sequence that concatenates the results of calling a given
+/// transformation with each element of this sequence.
 @available(SwiftStdlib 5.5, *)
 public struct AsyncFlatMapSequence<Base: AsyncSequence, SegmentOfResult: AsyncSequence> {
   @usableFromInline
@@ -42,9 +69,15 @@ public struct AsyncFlatMapSequence<Base: AsyncSequence, SegmentOfResult: AsyncSe
 
 @available(SwiftStdlib 5.5, *)
 extension AsyncFlatMapSequence: AsyncSequence {
+  /// The type of element produced by this asynchronous sequence.
+  ///
+  /// The flat map sequence produces the type of element in the asynchronous
+  /// sequence produced by the `transform` closure.
   public typealias Element = SegmentOfResult.Element
+  /// The type of iterator that produces elements of the sequence.
   public typealias AsyncIterator = Iterator
 
+  /// The iterator that produces elements of the flat map sequence.
   public struct Iterator: AsyncIteratorProtocol {
     @usableFromInline
     var baseIterator: Base.AsyncIterator
@@ -67,6 +100,15 @@ extension AsyncFlatMapSequence: AsyncSequence {
       self.transform = transform
     }
 
+    /// Produces the next element in the flat map sequence.
+    ///
+    /// This iterator calls `next()` on its base iterator; if this call returns
+    /// `nil`, `next()` returns `nil`. Otherwise, `next()` calls the
+    /// transforming closure on the received element, takes the resulting
+    /// asynchronous sequence, and creates an asynchronous iterator from it.
+    /// `next()` then consumes values from this iterator until it terminates.
+    /// At this point, `next()` is ready to receive the next value from the base
+    /// sequence.
     @inlinable
     public mutating func next() async rethrows -> SegmentOfResult.Element? {
       while !finished {