Backport: Use Swift 6.0 docs pipeline (#2966) (#2991)

Documentation checking catches more issues in Swift 6.0.

Adopt the Swift 6.0 image and fix the errors.

More accurate docs.

(cherry picked from commit adfd61a)

Co-authored-by: Rick Newton-Rogers <rnro@apple.com>

.github/workflows/pull_request.yml

@@ -10,8 +10,6 @@ jobs:
     uses: swiftlang/github-workflows/.github/workflows/soundness.yml@main
     with:
       license_header_check_project_name: "SwiftNIO"
-      # We need to move to 6.0 here but have to fix the new warnings first
-      docs_check_container_image: "swift:5.10-noble"
 
   unit-tests:
     name: Unit tests

Sources/NIOAsyncAwaitDemo/FullRequestResponse.swift

@@ -65,7 +65,7 @@ public final class RequestResponseHandler<Request, Response>: ChannelDuplexHandl
 
     /// Create a new `RequestResponseHandler`.
     ///
-    /// - parameters:
+    /// - Parameters:
     ///    - initialBufferCapacity: `RequestResponseHandler` saves the promises for all outstanding responses in a
     ///          buffer. `initialBufferCapacity` is the initial capacity for this buffer. You usually do not need to set
     ///          this parameter unless you intend to pipeline very deeply and don't want the buffer to resize.

Sources/NIOConcurrencyHelpers/NIOLock.swift

@@ -189,7 +189,7 @@ extension LockStorage: @unchecked Sendable {}
 
 /// A threading lock based on `libpthread` instead of `libdispatch`.
 ///
-/// - note: ``NIOLock`` has reference semantics.
+/// - Note: ``NIOLock`` has reference semantics.
 ///
 /// This object provides a lock on top of a single `pthread_mutex_t`. This kind
 /// of lock is safe to use with `libpthread`-based threading models, such as the

Sources/NIOConcurrencyHelpers/NIOLockedValueBox.swift

@@ -14,7 +14,7 @@
 
 /// Provides locked access to `Value`.
 ///
-/// - note: ``NIOLockedValueBox`` has reference semantics and holds the `Value`
+/// - Note: ``NIOLockedValueBox`` has reference semantics and holds the `Value`
 ///         alongside a lock behind a reference.
 ///
 /// This is no different than creating a ``Lock`` and protecting all

Sources/NIOCore/AsyncAwaitSupport.swift

@@ -58,9 +58,9 @@ extension EventLoopPromise {
     ///
     /// This function can be used to bridge the `async` world into an `EventLoopPromise`.
     ///
-    /// - parameters:
+    /// - Parameters:
     ///   - body: The `async` function to run.
-    /// - returns: A `Task` which was created to `await` the `body`.
+    /// - Returns: A `Task` which was created to `await` the `body`.
     @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *)
     @discardableResult
     @preconcurrency
@@ -82,24 +82,27 @@ extension EventLoopPromise {
 extension Channel {
     /// Shortcut for calling `write` and `flush`.
     ///
-    /// - parameters:
-    ///     - data: the data to write
-    ///     - promise: the `EventLoopPromise` that will be notified once the `write` operation completes,
-    ///                or `nil` if not interested in the outcome of the operation.
+    /// - Parameters:
+    ///   - data: the data to write
     @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *)
     @inlinable
-    public func writeAndFlush<T>(_ any: T) async throws {
-        try await self.writeAndFlush(any).get()
+    public func writeAndFlush<T>(_ data: T) async throws {
+        try await self.writeAndFlush(data).get()
     }
 
     /// Set `option` to `value` on this `Channel`.
+    /// - Parameters:
+    ///   - option: The option to set.
+    ///   - value: The new value of the option.
     @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *)
     @inlinable
     public func setOption<Option: ChannelOption>(_ option: Option, value: Option.Value) async throws {
         try await self.setOption(option, value: value).get()
     }
 
     /// Get the value of `option` for this `Channel`.
+    /// - Parameter option: The option to get.
+    /// - Returns: The value of the option.
     @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *)
     @inlinable
     public func getOption<Option: ChannelOption>(_ option: Option) async throws -> Option.Value {
@@ -109,56 +112,62 @@ extension Channel {
 
 extension ChannelOutboundInvoker {
     /// Register on an `EventLoop` and so have all its IO handled.
-    ///
-    /// - returns: the future which will be notified once the operation completes.
+    /// - Parameters:
+    ///   - file: The file this function was called in, for debugging purposes.
+    ///   - line: The line this function was called on, for debugging purposes.
     @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *)
     public func register(file: StaticString = #fileID, line: UInt = #line) async throws {
         try await self.register(file: file, line: line).get()
     }
 
     /// Bind to a `SocketAddress`.
-    /// - parameters:
-    ///     - to: the `SocketAddress` to which we should bind the `Channel`.
-    /// - returns: the future which will be notified once the operation completes.
+    /// - Parameters:
+    ///   - address: the `SocketAddress` to which we should bind the `Channel`.
+    ///   - file: The file this function was called in, for debugging purposes.
+    ///   - line: The line this function was called on, for debugging purposes.
     @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *)
     public func bind(to address: SocketAddress, file: StaticString = #fileID, line: UInt = #line) async throws {
         try await self.bind(to: address, file: file, line: line).get()
     }
 
     /// Connect to a `SocketAddress`.
-    /// - parameters:
-    ///     - to: the `SocketAddress` to which we should connect the `Channel`.
-    /// - returns: the future which will be notified once the operation completes.
+    /// - Parameters:
+    ///   - address: the `SocketAddress` to which we should connect the `Channel`.
+    ///   - file: The file this function was called in, for debugging purposes.
+    ///   - line: The line this function was called on, for debugging purposes.
     @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *)
     public func connect(to address: SocketAddress, file: StaticString = #fileID, line: UInt = #line) async throws {
         try await self.connect(to: address, file: file, line: line).get()
     }
 
     /// Shortcut for calling `write` and `flush`.
     ///
-    /// - parameters:
-    ///     - data: the data to write
-    /// - returns: the future which will be notified once the `write` operation completes.
+    /// - Parameters:
+    ///   - data: the data to write
+    ///   - file: The file this function was called in, for debugging purposes.
+    ///   - line: The line this function was called on, for debugging purposes.
     @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *)
     public func writeAndFlush(_ data: NIOAny, file: StaticString = #fileID, line: UInt = #line) async throws {
         try await self.writeAndFlush(data, file: file, line: line).get()
     }
 
     /// Close the `Channel` and so the connection if one exists.
     ///
-    /// - parameters:
-    ///     - mode: the `CloseMode` that is used
-    /// - returns: the future which will be notified once the operation completes.
+    /// - Parameters:
+    ///   - mode: the `CloseMode` that is used
+    ///   - file: The file this function was called in, for debugging purposes.
+    ///   - line: The line this function was called on, for debugging purposes.
     @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *)
     public func close(mode: CloseMode = .all, file: StaticString = #fileID, line: UInt = #line) async throws {
         try await self.close(mode: mode, file: file, line: line).get()
     }
 
     /// Trigger a custom user outbound event which will flow through the `ChannelPipeline`.
     ///
-    /// - parameters:
-    ///     - event: the event itself.
-    /// - returns: the future which will be notified once the operation completes.
+    /// - Parameters:
+    ///   - event: the event itself.
+    ///   - file: The file this function was called in, for debugging purposes.
+    ///   - line: The line this function was called on, for debugging purposes.
     @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *)
     public func triggerUserOutboundEvent(_ event: Any, file: StaticString = #fileID, line: UInt = #line) async throws {
         try await self.triggerUserOutboundEvent(event, file: file, line: line).get()

Sources/NIOCore/AsyncSequences/NIOAsyncSequenceProducer.swift

@@ -290,7 +290,7 @@ extension NIOAsyncSequenceProducer {
         /// This can be called more than once and returns to the caller immediately
         /// without blocking for any awaiting consumption from the iteration.
         ///
-        /// - Parameter contentsOf: The sequence to yield.
+        /// - Parameter sequence: The sequence to yield.
         /// - Returns: A ``NIOAsyncSequenceProducer/Source/YieldResult`` that indicates if the yield was successful
         /// and if more elements should be produced.
         @inlinable

Sources/NIOCore/AsyncSequences/NIOAsyncWriter.swift

@@ -279,7 +279,7 @@ public struct NIOAsyncWriter<
     ///
     /// This can be called more than once and from multiple `Task`s at the same time.
     ///
-    /// - Parameter contentsOf: The sequence to yield.
+    /// - Parameter sequence: The sequence to yield.
     @inlinable
     public func yield<S: Sequence>(contentsOf sequence: S) async throws where S.Element == Element {
         try await self._storage.yield(contentsOf: sequence)

Sources/NIOCore/AsyncSequences/NIOThrowingAsyncSequenceProducer.swift

@@ -335,7 +335,7 @@ extension NIOThrowingAsyncSequenceProducer {
         /// This can be called more than once and returns to the caller immediately
         /// without blocking for any awaiting consumption from the iteration.
         ///
-        /// - Parameter contentsOf: The sequence to yield.
+        /// - Parameter sequence: The sequence to yield.
         /// - Returns: A ``NIOThrowingAsyncSequenceProducer/Source/YieldResult`` that indicates if the yield was successful
         /// and if more elements should be produced.
         @inlinable