[GHA] Documentation check (#2764)

# Motivation

Next up replacing the documentation check.

# Modification

This moves the current approach of the script into a GH action. I tried just running the documentation check against all targets but that also results in warnings from downstream deps in their docs to show up.

I also fixed up some new errors that appeared since our current pipeline was running on 5.8.

# Result

Next CI job migrated to GHA

.github/workflows/pull_requests.yml

@@ -32,7 +32,7 @@ jobs:
       run: swift test
 
   api-breakage:
-    name: API breakage checks
+    name: API breakage check
     runs-on: ubuntu-latest
     container:
       image: swift:5.10-noble
@@ -47,4 +47,25 @@ jobs:
       # https://github.com/actions/checkout/issues/766
       run: git config --global --add safe.directory ${GITHUB_WORKSPACE}
     - name: Run API breakage check
-      run: swift package diagnose-api-breaking-changes origin/main
+      run: swift package diagnose-api-breaking-changes origin/main
+
+  docs-check:
+    name: Documentation check
+    runs-on: ubuntu-latest
+    container:
+      image: swift:5.10-noble
+    timeout-minutes: 20
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+    - name: Run documentation check
+      shell: bash
+      run: |
+        set -eu
+
+        raw_targets=$(sed -E -n -e 's/^.* - documentation_targets: \[(.*)\].*$/\1/p' .spi.yml)
+        targets=(${raw_targets//,/ })
+
+        for target in "${targets[@]}"; do
+          swift package plugin generate-documentation --target "$target" --warnings-as-errors --analyze --level detailed
+        done

Sources/NIOCore/AsyncAwaitSupport.swift

@@ -225,7 +225,7 @@ public struct NIOTooManyBytesError: Error, Hashable {
 
 @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *)
 extension AsyncSequence where Element: RandomAccessCollection, Element.Element == UInt8 {
-    /// Accumulates an ``Swift/AsyncSequence`` of ``Swift/RandomAccessCollection``s into a single `accumulationBuffer`.
+    /// Accumulates an `AsyncSequence` of `RandomAccessCollection`s into a single `accumulationBuffer`.
     /// - Parameters:
     ///   - accumulationBuffer: buffer to write all the elements of `self` into
     ///   - maxBytes: The maximum number of bytes this method is allowed to write into `accumulationBuffer`
@@ -247,7 +247,7 @@ extension AsyncSequence where Element: RandomAccessCollection, Element.Element =
         }
     }
 
-    /// Accumulates an ``Swift/AsyncSequence`` of ``Swift/RandomAccessCollection``s into a single ``ByteBuffer``.
+    /// Accumulates an `AsyncSequence` of `RandomAccessCollection`s into a single ``ByteBuffer``.
     /// - Parameters:
     ///   - maxBytes: The maximum number of bytes this method is allowed to accumulate
     ///   - allocator: Allocator used for allocating the result `ByteBuffer`

Sources/NIOCore/AsyncChannel/AsyncChannel.swift

@@ -26,7 +26,7 @@
 /// does not expose the following functionality:
 ///
 /// - user events
-/// - traditional NIO back pressure such as writability signals and the ``Channel/read()`` call
+/// - traditional NIO back pressure such as writability signals and the channel's read call
 ///
 /// Users are encouraged to separate their ``ChannelHandler``s into those that implement
 /// protocol-specific logic (such as parsers and encoders) and those that implement business

Sources/NIOCore/EventLoop.swift

@@ -314,7 +314,7 @@ public protocol EventLoop: EventLoopGroup {
     /// This executor can be used to isolate an actor to a given ``EventLoop``. Implementers are encouraged to customise
     /// this implementation by conforming their ``EventLoop`` to ``NIOSerialEventLoopExecutor`` which will provide an
     /// optimised implementation of this method, and will conform their type to `SerialExecutor`. The default
-    /// implementation returns a ``NIODefaultSerialEventLoopExecutor`` instead, which provides suboptimal performance.
+    /// implementation provides suboptimal performance.
     @available(macOS 14.0, iOS 17.0, watchOS 10.0, tvOS 17.0, *)
     var executor: any SerialExecutor { get }
 

Sources/NIOFileSystem/FileSystem.swift

@@ -656,7 +656,7 @@ public struct FileSystem: Sendable, FileSystemProtocol {
 extension NIOSingletons {
     /// A suggestion of how many threads the global singleton ``FileSystem`` uses for blocking I/O.
     ///
-    /// The thread count is ``System/coreCount`` unless the environment variable
+    /// The thread count is the system's available core count unless the environment variable
     /// `NIO_SINGLETON_FILESYSTEM_THREAD_COUNT` is set or this value was set manually by the user.
     ///
     /// - note: This value must be set _before_ any singletons are used and must only be set once.