Add a basic CI step for checking documentation comments

Using the SwiftPM DocC Plugin because [1] describes it as the “preferred option”. Part of #1. [1] https://www.swift.org/documentation/docc/documenting-a-swift-framework-or-package
ably · Nov 28, 2024 · 3e09520 · 3e09520
1 parent d1db8c2
commit 3e09520
Show file tree

Hide file tree

Showing 5 changed files with 94 additions and 2 deletions.
diff --git a/.github/workflows/check.yaml b/.github/workflows/check.yaml
@@ -139,6 +139,21 @@ jobs:
       - name: Build example app
         run: swift run BuildTool build-example-app --platform ${{ matrix.platform }}
 
+  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
+        run: swift run BuildTool build-documentation
+
   # 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
@@ -152,6 +167,7 @@ jobs:
       - check-spm
       - check-xcode
       - check-example-app
+      - check-documentation
 
     steps:
       - name: No-op

diff --git 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
@@ -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
@@ -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(

diff --git a/Sources/BuildTool/BuildTool.swift b/Sources/BuildTool/BuildTool.swift
@@ -14,6 +14,7 @@ struct BuildTool: AsyncParsableCommand {
             GenerateMatrices.self,
             Lint.self,
             SpecCoverage.self,
+            BuildDocumentation.self,
         ]
     )
 }
@@ -650,3 +651,38 @@ struct SpecCoverage: AsyncParsableCommand {
         }
     }
 }
+
+@available(macOS 14, *)
+struct BuildDocumentation: AsyncParsableCommand {
+    static let configuration = CommandConfiguration(
+        abstract: "Build documentation for the library"
+    )
+
+    mutating func run() async throws {
+        // 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.
+
+        try await ProcessRunner.run(
+            executableName: "swift",
+            arguments: [
+                "package",
+                "generate-documentation",
+
+                "--product", "AblyChat",
+
+                // Useful because it alerts us about links to nonexistent symbols.
+                "--warnings-as-errors",
+
+                // 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.
+                "--experimental-documentation-coverage",
+
+                // Increases the detail level of the aforementioned coverage table in CLI output.
+                "--coverage-summary-level", "detailed",
+            ]
+        )
+    }
+}