Add a smattering of brief inline docs for most functions/types (apple#97)

Author: phausler

Sources/AsyncAlgorithms/AsyncCompactedSequence.swift

@@ -23,6 +23,7 @@ public struct AsyncCompactedSequence<Base: AsyncSequence, Element>: AsyncSequenc
     self.base = base
   }
 
+  /// The iterator for an `AsyncCompactedSequence` instance.
   @frozen
   public struct Iterator: AsyncIteratorProtocol {
     @usableFromInline

Sources/AsyncAlgorithms/AsyncExclusiveReductionsSequence.swift

@@ -70,6 +70,7 @@ public struct AsyncExclusiveReductionsSequence<Base: AsyncSequence, Element> {
 }
 
 extension AsyncExclusiveReductionsSequence: AsyncSequence {
+  /// The iterator for an `AsyncExclusiveReductionsSequence` instance.
   @frozen
   public struct Iterator: AsyncIteratorProtocol {
     @usableFromInline

Sources/AsyncAlgorithms/AsyncInclusiveReductionsSequence.swift

@@ -25,6 +25,8 @@ extension AsyncSequence {
   }
 }
 
+/// An asynchronous sequence containing the accumulated results of combining the
+/// elements of the asynchronous sequence using a given closure.
 @frozen
 public struct AsyncInclusiveReductionsSequence<Base: AsyncSequence> {
   @usableFromInline
@@ -43,6 +45,7 @@ public struct AsyncInclusiveReductionsSequence<Base: AsyncSequence> {
 extension AsyncInclusiveReductionsSequence: AsyncSequence {
   public typealias Element = Base.Element
 
+  /// The iterator for an `AsyncInclusiveReductionsSequence` instance.
   @frozen
   public struct Iterator: AsyncIteratorProtocol {
     @usableFromInline

Sources/AsyncAlgorithms/AsyncJoinedBySeparatorSequence.swift

@@ -10,16 +10,19 @@
 //===----------------------------------------------------------------------===//
 
 extension AsyncSequence where Element: AsyncSequence {
+  /// Concatenate an `AsyncSequence` of `AsyncSequence` elements with a seperator.
   @inlinable
   public func joined<Separator: AsyncSequence>(separator: Separator) -> AsyncJoinedBySeparatorSequence<Self, Separator> {
     return AsyncJoinedBySeparatorSequence(self, separator: separator)
   }
 }
 
+/// An `AsyncSequence` that concatenates`AsyncSequence` elements with a seperator.
 public struct AsyncJoinedBySeparatorSequence<Base: AsyncSequence, Separator: AsyncSequence>: AsyncSequence where Base.Element: AsyncSequence, Separator.Element == Base.Element.Element {
   public typealias Element = Base.Element.Element
   public typealias AsyncIterator = Iterator
 
+  /// The iterator for an `AsyncJoinedBySeparatorSequence` instance.
   public struct Iterator: AsyncIteratorProtocol {
     @usableFromInline
     enum State {

Sources/AsyncAlgorithms/AsyncJoinedSequence.swift

@@ -10,17 +10,20 @@
 //===----------------------------------------------------------------------===//
 
 extension AsyncSequence where Element: AsyncSequence {
+  /// Concatenate an `AsyncSequence` of `AsyncSequence` elements 
   @inlinable
   public func joined() -> AsyncJoinedSequence<Self> {
     return AsyncJoinedSequence(self)
   }
 }
 
+/// An `AsyncSequence` that concatenates`AsyncSequence` elements
 @frozen
 public struct AsyncJoinedSequence<Base: AsyncSequence>: AsyncSequence where Base.Element: AsyncSequence {
   public typealias Element = Base.Element.Element
   public typealias AsyncIterator = Iterator
 
+  /// The iterator for an `AsyncJoinedSequence` instance.
   @frozen
   public struct Iterator: AsyncIteratorProtocol {
     @usableFromInline

Sources/AsyncAlgorithms/AsyncRemoveDuplicatesSequence.swift

@@ -10,6 +10,7 @@
 //===----------------------------------------------------------------------===//
 
 extension AsyncSequence where Element: Equatable {
+  /// Creates an asynchronous sequence that omits repeated elements.
   public func removeDuplicates() -> AsyncRemoveDuplicatesSequence<Self> {
     AsyncRemoveDuplicatesSequence(self) { lhs, rhs in
       lhs == rhs
@@ -18,18 +19,22 @@ extension AsyncSequence where Element: Equatable {
 }
 
 extension AsyncSequence {
+  /// Creates an asynchronous sequence that omits repeated elements by testing them with a predicate.
   public func removeDuplicates(by predicate: @escaping @Sendable (Element, Element) async -> Bool) -> AsyncRemoveDuplicatesSequence<Self> {
     return AsyncRemoveDuplicatesSequence(self, predicate: predicate)
   }
 
+  /// Creates an asynchronous sequence that omits repeated elements by testing them with a predicate.
   public func removeDuplicates(by predicate: @escaping @Sendable (Element, Element) async throws -> Bool) -> AsyncThrowingRemoveDuplicatesSequence<Self> {
     return AsyncThrowingRemoveDuplicatesSequence(self, predicate: predicate)
   }
 }
 
+/// An asynchronous sequence that omits repeated elements by testing them with a predicate.
 public struct AsyncRemoveDuplicatesSequence<Base: AsyncSequence>: AsyncSequence {
   public typealias Element = Base.Element
 
+  /// The iterator for an `AsyncRemoveDuplicatesSequence` instance.
   public struct Iterator: AsyncIteratorProtocol {
 
     @usableFromInline
@@ -84,9 +89,11 @@ extension AsyncRemoveDuplicatesSequence: Sendable where Base: Sendable, Base.Ele
 extension AsyncRemoveDuplicatesSequence.Iterator: Sendable where Base: Sendable, Base.Element: Sendable, Base.AsyncIterator: Sendable { }
 
 
+/// An asynchronous sequence that omits repeated elements by testing them with a predicate.
 public struct AsyncThrowingRemoveDuplicatesSequence<Base: AsyncSequence>: AsyncSequence {
   public typealias Element = Base.Element
 
+  /// The iterator for an `AsyncThrowingRemoveDuplicatesSequence` instance.
   public struct Iterator: AsyncIteratorProtocol {
 
     @usableFromInline

Sources/AsyncAlgorithms/AsyncThrottleSequence.swift

@@ -10,16 +10,19 @@
 //===----------------------------------------------------------------------===//
 
 extension AsyncSequence {
+  /// Create a rate limited `AsyncSequence` by emitting values at most every specified interval.
   @available(macOS 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
   public func throttle<C: Clock, Reduced>(for interval: C.Instant.Duration, clock: C, reducing: @Sendable @escaping (Reduced?, Element) async -> Reduced) -> AsyncThrottleSequence<Self, C, Reduced> {
     AsyncThrottleSequence(self, interval: interval, clock: clock, reducing: reducing)
   }
 
+  /// Create a rate limited `AsyncSequence` by emitting values at most every specified interval.
   @available(macOS 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
   public func throttle<Reduced>(for interval: Duration, reducing: @Sendable @escaping (Reduced?, Element) async -> Reduced) -> AsyncThrottleSequence<Self, ContinuousClock, Reduced> {
     throttle(for: interval, clock: .continuous, reducing: reducing)
   }
 
+  /// Create a rate limited `AsyncSequence` by emitting values at most every specified interval.
   @available(macOS 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
   public func throttle<C: Clock>(for interval: C.Instant.Duration, clock: C, latest: Bool = true) -> AsyncThrottleSequence<Self, C, Element> {
     throttle(for: interval, clock: clock) { previous, element in
@@ -31,12 +34,14 @@ extension AsyncSequence {
     }
   }
 
+  /// Create a rate limited `AsyncSequence` by emitting values at most every specified interval.
   @available(macOS 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
   public func throttle(for interval: Duration, latest: Bool = true) -> AsyncThrottleSequence<Self, ContinuousClock, Element> {
     throttle(for: interval, clock: .continuous, latest: latest)
   }
 }
 
+/// A rate limited `AsyncSequence` by emitting values at most every specified interval.
 @available(macOS 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
 public struct AsyncThrottleSequence<Base: AsyncSequence, C: Clock, Reduced> {
   let base: Base
@@ -56,6 +61,7 @@ public struct AsyncThrottleSequence<Base: AsyncSequence, C: Clock, Reduced> {
 extension AsyncThrottleSequence: AsyncSequence {
   public typealias Element = Reduced
 
+  /// The iterator for an `AsyncThrottleSequence` instance.
   public struct Iterator: AsyncIteratorProtocol {
     var base: Base.AsyncIterator
     let interval: C.Instant.Duration

Sources/AsyncAlgorithms/AsyncThrowingChannel.swift

@@ -13,6 +13,7 @@
 ///
 /// The `AsyncThrowingChannel` class is intended to be used as a communication types between tasks., particularly when one task produces values and another task consumes those values. The back pressure applied by `send(_:)`, `fail(_:)` and `finish()` via the suspension/resume ensure that the production of values does not exceed the consumption of values from iteration. Each of these methods suspends after enqueuing the event and is resumed when the next call to `next()` on the `Iterator` is made.
 public final class AsyncThrowingChannel<Element: Sendable, Failure: Error>: AsyncSequence, Sendable {
+  /// The iterator for an `AsyncThrowingChannel` instance.
   public struct Iterator: AsyncIteratorProtocol, Sendable {
     let channel: AsyncThrowingChannel<Element, Failure>
     var active: Bool = true
@@ -188,14 +189,20 @@ public final class AsyncThrowingChannel<Element: Sendable, Failure: Error>: Asyn
     continuation?.resume(with: result)
   }
 
+  /// Send an element to an awaiting iteration. This function will resume when the next call to `next()` is made.
+  /// If the channel is already finished then this returns immediately
   public func send(_ element: Element) async {
       await _send(.success(element))
   }
 
+  /// Send an error to an awaiting iteration. This function will resume when the next call to `next()` is made.
+  /// If the channel is already finished then this returns immediately
   public func fail(_ error: Error) async where Failure == Error {
     await _send(.failure(error))
   }
 
+  /// Send a finish to an awaiting iteration. This function will resume when the next call to `next()` is made.
+  /// If the channel is already finished then this returns immediately
   public func finish() async {
       await _send(.success(nil))
   }

Sources/AsyncAlgorithms/AsyncThrowingExclusiveReductionsSequence.swift

@@ -72,6 +72,7 @@ public struct AsyncThrowingExclusiveReductionsSequence<Base: AsyncSequence, Elem
 }
 
 extension AsyncThrowingExclusiveReductionsSequence: AsyncSequence {
+  /// The iterator for an `AsyncThrowingExclusiveReductionsSequence` instance.
   @frozen
   public struct Iterator: AsyncIteratorProtocol {
     @usableFromInline

Sources/AsyncAlgorithms/AsyncThrowingInclusiveReductionsSequence.swift

@@ -24,6 +24,8 @@ extension AsyncSequence {
   }
 }
 
+/// An asynchronous sequence containing the accumulated results of combining the
+/// elements of the asynchronous sequence using a given error-throwing closure.
 @frozen
 public struct AsyncThrowingInclusiveReductionsSequence<Base: AsyncSequence> {
   @usableFromInline
@@ -42,6 +44,7 @@ public struct AsyncThrowingInclusiveReductionsSequence<Base: AsyncSequence> {
 extension AsyncThrowingInclusiveReductionsSequence: AsyncSequence {
   public typealias Element = Base.Element
 
+  /// The iterator for an `AsyncThrowingInclusiveReductionsSequence` instance.
   @frozen
   public struct Iterator: AsyncIteratorProtocol {
     @usableFromInline

Sources/AsyncAlgorithms/AsyncTimerSequence.swift

@@ -9,10 +9,12 @@
 //
 //===----------------------------------------------------------------------===//
 
+/// An `AsyncSequence` that produces elements at regular intervals.
 @available(macOS 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
 public struct AsyncTimerSequence<C: Clock>: AsyncSequence {
   public typealias Element = C.Instant
 
+  /// The iterator for an `AsyncTimerSequence` instance.
   public struct Iterator: AsyncIteratorProtocol {
     var clock: C?
     let interval: C.Instant.Duration
@@ -57,6 +59,7 @@ public struct AsyncTimerSequence<C: Clock>: AsyncSequence {
   let interval: C.Instant.Duration
   let tolerance: C.Instant.Duration?
 
+  /// Create an `AsyncTimerSequence` with a given repeating interval.
   public init(interval: C.Instant.Duration, tolerance: C.Instant.Duration? = nil, clock: C) {
     self.clock = clock
     self.interval = interval
@@ -70,13 +73,15 @@ public struct AsyncTimerSequence<C: Clock>: AsyncSequence {
 
 @available(macOS 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
 extension AsyncTimerSequence {
+  /// Create an `AsyncTimerSequence` with a given repeating interval.
   public static func repeating(every interval: C.Instant.Duration, tolerance: C.Instant.Duration? = nil, clock: C) -> AsyncTimerSequence<C> {
     return AsyncTimerSequence(interval: interval, tolerance: tolerance, clock: clock)
   }
 }
 
 @available(macOS 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
 extension AsyncTimerSequence where C == SuspendingClock {
+  /// Create an `AsyncTimerSequence` with a given repeating interval.
   public static func repeating(every interval: Duration, tolerance: Duration? = nil) -> AsyncTimerSequence<SuspendingClock> {
     return AsyncTimerSequence(interval: interval, tolerance: tolerance, clock: SuspendingClock())
   }

Sources/AsyncAlgorithms/AsyncZip2Sequence.swift

@@ -9,6 +9,8 @@
 //
 //===----------------------------------------------------------------------===//
 
+/// Creates an asynchronous sequence that concurrently awaits values from two `AsyncSequence` types
+/// by emitting a tuple of the values.
 public func zip<Base1: AsyncSequence, Base2: AsyncSequence>(_ base1: Base1, _ base2: Base2) -> AsyncZip2Sequence<Base1, Base2>
   where Base1: Sendable,
         Base2: Sendable,
@@ -19,6 +21,8 @@ public func zip<Base1: AsyncSequence, Base2: AsyncSequence>(_ base1: Base1, _ ba
   AsyncZip2Sequence(base1, base2)
 }
 
+/// An asynchronous sequence that concurrently awaits values from two `AsyncSequence` types
+/// by emitting a tuple of the values.
 public struct AsyncZip2Sequence<Base1: AsyncSequence, Base2: AsyncSequence>: Sendable
   where Base1: Sendable,
         Base2: Sendable,
@@ -38,6 +42,7 @@ public struct AsyncZip2Sequence<Base1: AsyncSequence, Base2: AsyncSequence>: Sen
 extension AsyncZip2Sequence: AsyncSequence {
   public typealias Element = (Base1.Element, Base2.Element)
 
+  /// The iterator for an `AsyncZip2Sequence` instance.
   public struct Iterator: AsyncIteratorProtocol, Sendable {
     var base1: Base1.AsyncIterator?
     var base2: Base2.AsyncIterator?

Sources/AsyncAlgorithms/AsyncZip3Sequence.swift

@@ -9,6 +9,8 @@
 //
 //===----------------------------------------------------------------------===//
 
+/// Creates an asynchronous sequence that concurrently awaits values from three `AsyncSequence` types
+/// by emitting a tuple of the values.
 public func zip<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>(_ base1: Base1, _ base2: Base2, _ base3: Base3) -> AsyncZip3Sequence<Base1, Base2, Base3>
   where Base1: Sendable,
         Base2: Sendable,
@@ -22,6 +24,8 @@ public func zip<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence
   AsyncZip3Sequence(base1, base2, base3)
 }
 
+/// An asynchronous sequence that concurrently awaits values from three `AsyncSequence` types
+/// by emitting a tuple of the values.
 public struct AsyncZip3Sequence<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>: Sendable
   where Base1: Sendable,
         Base2: Sendable,
@@ -46,6 +50,7 @@ public struct AsyncZip3Sequence<Base1: AsyncSequence, Base2: AsyncSequence, Base
 extension AsyncZip3Sequence: AsyncSequence {
   public typealias Element = (Base1.Element, Base2.Element, Base3.Element)
 
+  /// The iterator for an `AsyncZip3Sequence` instance.
   public struct Iterator: AsyncIteratorProtocol, Sendable {
     var base1: Base1.AsyncIterator?
     var base2: Base2.AsyncIterator?