Skip to content

Commit

Permalink
[GHA] Documentation check
Browse files Browse the repository at this point in the history
# 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
  • Loading branch information
FranzBusch committed Jul 4, 2024
1 parent 9d5d0b6 commit 06aa590
Show file tree
Hide file tree
Showing 5 changed files with 28 additions and 7 deletions.
25 changes: 23 additions & 2 deletions .github/workflows/pull_requests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
4 changes: 2 additions & 2 deletions Sources/NIOCore/AsyncAwaitSupport.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand All @@ -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`
Expand Down
2 changes: 1 addition & 1 deletion Sources/NIOCore/AsyncChannel/AsyncChannel.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion Sources/NIOCore/EventLoop.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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 }

Expand Down
2 changes: 1 addition & 1 deletion Sources/NIOFileSystem/FileSystem.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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 systems 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.
Expand Down

0 comments on commit 06aa590

Please sign in to comment.