diff --git a/.github/workflows/check.yaml b/.github/workflows/check.yaml index 1a5b09c5..44be1156 100644 --- a/.github/workflows/check.yaml +++ b/.github/workflows/check.yaml @@ -139,6 +139,36 @@ jobs: - name: Build example app run: swift run BuildTool build-example-app --platform ${{ matrix.platform }} + # For now, this is intended to just perform some validation of the documentation comments. We’ll generate HTML output in https://github.com/ably/ably-chat-swift/issues/2. + check-documentation: + runs-on: macos-15 + steps: + - uses: actions/checkout@v4 + with: + submodules: true + + # This step can be removed once the runners’ default version of Xcode is 16 or above + - uses: maxim-lobanov/setup-xcode@v1 + with: + xcode-version: 16 + + - name: Build documentation + # --warnings-as-errors: Useful because it alerts us about links to nonexistent symbols. + # + # --experimental-documentation-coverage: Outputs the following information about which symbols have been documented and to what level of detail: + # - a table at the end of the CLI output + # - as a JSON file in ./.build/plugins/Swift-DocC/outputs/AblyChat.doccarchive/documentation-coverage.json + # + # I do not yet know how to make use of these (there’s all sorts of unexpected symbols that we didn’t directly declare there, e.g. `compactMap(_:)`), but maybe it’ll be a bit helpful still. + # + # --coverage-summary-level: Increases the detail level of the aforementioned coverage table in CLI output. + run: | + swift package generate-documentation \ + --product AblyChat \ + --warnings-as-errors \ + --experimental-documentation-coverage \ + --coverage-summary-level detailed + # We use this job as a marker that all of the required checks have completed. # This allows us to configure a single required status check in our branch # protection rules instead of having to type loads of different check names @@ -148,6 +178,7 @@ jobs: runs-on: ubuntu-latest needs: - lint + - check-documentation - spec-coverage - check-spm - check-xcode diff --git a/AblyChat.xcworkspace/xcshareddata/swiftpm/Package.resolved b/AblyChat.xcworkspace/xcshareddata/swiftpm/Package.resolved index 6e17fa1e..396b0e70 100644 --- a/AblyChat.xcworkspace/xcshareddata/swiftpm/Package.resolved +++ b/AblyChat.xcworkspace/xcshareddata/swiftpm/Package.resolved @@ -1,5 +1,5 @@ { - "originHash" : "1ad2d7338668d15feccbf564582941161acd47349bfca8f34374e11c69677ae8", + "originHash" : "1547951218aae39e26117fe3ca69bba0858841246ead50ef24e9592cdbcfa481", "pins" : [ { "identity" : "ably-cocoa", @@ -55,6 +55,24 @@ "version" : "1.1.2" } }, + { + "identity" : "swift-docc-plugin", + "kind" : "remoteSourceControl", + "location" : "https://github.com/apple/swift-docc-plugin", + "state" : { + "revision" : "85e4bb4e1cd62cec64a4b8e769dcefdf0c5b9d64", + "version" : "1.4.3" + } + }, + { + "identity" : "swift-docc-symbolkit", + "kind" : "remoteSourceControl", + "location" : "https://github.com/swiftlang/swift-docc-symbolkit", + "state" : { + "revision" : "b45d1f2ed151d057b54504d653e0da5552844e34", + "version" : "1.0.0" + } + }, { "identity" : "table", "kind" : "remoteSourceControl", diff --git a/Package.resolved b/Package.resolved index 30ea3e1d..1ebd6d6a 100644 --- a/Package.resolved +++ b/Package.resolved @@ -1,5 +1,5 @@ { - "originHash" : "b6d25f160b01b473629481d68d4fe734b3981fcd87079531f784c2ade3afdc4d", + "originHash" : "19ff3d71167d4ac328655c520d3210baa89ea2c1b0900fb1b5ac5c770b42fa28", "pins" : [ { "identity" : "ably-cocoa", @@ -55,6 +55,24 @@ "version" : "1.1.2" } }, + { + "identity" : "swift-docc-plugin", + "kind" : "remoteSourceControl", + "location" : "https://github.com/apple/swift-docc-plugin", + "state" : { + "revision" : "85e4bb4e1cd62cec64a4b8e769dcefdf0c5b9d64", + "version" : "1.4.3" + } + }, + { + "identity" : "swift-docc-symbolkit", + "kind" : "remoteSourceControl", + "location" : "https://github.com/swiftlang/swift-docc-symbolkit", + "state" : { + "revision" : "b45d1f2ed151d057b54504d653e0da5552844e34", + "version" : "1.0.0" + } + }, { "identity" : "table", "kind" : "remoteSourceControl", diff --git a/Package.swift b/Package.swift index 06d664d4..b3407bb0 100644 --- a/Package.swift +++ b/Package.swift @@ -35,6 +35,10 @@ let package = Package( url: "https://github.com/JanGorman/Table.git", from: "1.1.1" ), + .package( + url: "https://github.com/apple/swift-docc-plugin", + from: "1.0.0" + ), ], targets: [ .target(