[WIP] First pass at some documentation for AsyncChannel (#91)

* First pass at some documentation for AsyncChannel

* Apply suggestions from code review

Co-authored-by: Chris Adamson <[email protected]>

* Manually line break docs

Co-authored-by: Chris Adamson <[email protected]>

Author: phausler

Sources/AsyncAlgorithms/AsyncChannel.swift

@@ -9,7 +9,16 @@
 //
 //===----------------------------------------------------------------------===//
 
+/// A channel for sending elements from on task to another with back pressure.
+///
+/// The `AsyncChannel` class is intended to be used as a communication type between tasks,
+/// particularly when one task produces values and another task consumes those values. The back
+///  pressure applied by `send(_:)` 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 AsyncChannel<Element: Sendable>: AsyncSequence, Sendable {
+  /// The iterator for a `AsyncChannel` instance.
   public struct Iterator: AsyncIteratorProtocol, Sendable {
     let channel: AsyncChannel<Element>
     var active: Bool = true
@@ -18,6 +27,7 @@ public final class AsyncChannel<Element: Sendable>: AsyncSequence, Sendable {
       self.channel = channel
     }
 
+    /// Await the next sent element or finish.
     public mutating func next() async -> Element? {
       guard active else {
         return nil
@@ -98,6 +108,7 @@ public final class AsyncChannel<Element: Sendable>: AsyncSequence, Sendable {
 
   let state = ManagedCriticalState(State())
 
+  /// Create a new `AsyncChannel` given an element type.
   public init(element elementType: Element.Type = Element.self) { }
 
   func establish() -> Int {
@@ -180,14 +191,19 @@ public final class AsyncChannel<Element: Sendable>: AsyncSequence, Sendable {
     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 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))
   }
 
+  /// Create an `Iterator` for iteration of an `AsyncChannel`
   public func makeAsyncIterator() -> Iterator {
     return Iterator(self)
   }

Sources/AsyncAlgorithms/AsyncThrowingChannel.swift

@@ -9,6 +9,9 @@
 //
 //===----------------------------------------------------------------------===//
 
+/// A throwing channel for sending elements from on task to another with back pressure.
+///
+/// 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 {
   public struct Iterator: AsyncIteratorProtocol, Sendable {
     let channel: AsyncThrowingChannel<Element, Failure>