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

.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

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",

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",

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(