Build Swift docs in CI

Fix existing documentation issues. Prevent backsliding on documentation by 
requiring cross-links to be correct for CI checks to pass.

.github/workflows/build_and_test.yml

@@ -336,6 +336,10 @@ jobs:
       run: swift test -v
       working-directory: swift
 
+    - name: Build Swift package documentation
+      run: swift package plugin generate-documentation --analyze --warnings-as-errors
+      working-directory: swift
+
   swift_cocoapod:
     name: Swift CocoaPod
 

swift/Package.resolved

@@ -0,0 +1,25 @@
+{
+  "object": {
+    "pins": [
+      {
+        "package": "SwiftDocCPlugin",
+        "repositoryURL": "https://github.com/apple/swift-docc-plugin",
+        "state": {
+          "branch": null,
+          "revision": "26ac5758409154cc448d7ab82389c520fa8a8247",
+          "version": "1.3.0"
+        }
+      },
+      {
+        "package": "SymbolKit",
+        "repositoryURL": "https://github.com/apple/swift-docc-symbolkit",
+        "state": {
+          "branch": null,
+          "revision": "b45d1f2ed151d057b54504d653e0da5552844e34",
+          "version": "1.0.0"
+        }
+      }
+    ]
+  },
+  "version": 1
+}

swift/Package.swift

@@ -20,7 +20,9 @@ let package = Package(
             targets: ["LibSignalClient"]
         )
     ],
-    dependencies: [],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.3.0"),
+    ],
     targets: [
         .systemLibrary(name: "SignalFfi"),
         .target(

swift/Sources/LibSignalClient/Pin.swift

@@ -77,7 +77,7 @@ public class PinHash: NativeHandleOwner {
     /// Hash a pin for use with a remote SecureValueRecovery1 service.
     ///
     /// Note: This should be used with SVR1 only. For SVR1, the salt should be the backup id.
-    /// For SVR2 clients, use ``PinHash/init(pin:username:mrenclave:)`` which handles salt construction.
+    /// For SVR2 clients, use ``PinHash/init(normalizedPin:username:mrenclave:)`` which handles salt construction.
     ///
     /// - parameter normalizedPin: A normalized, UTF-8 encoded byte representation of the pin to verify
     /// - parameter salt: A 32 byte salt
@@ -97,7 +97,7 @@ public class PinHash: NativeHandleOwner {
 
     /// Hash a pin for use with a remote SecureValueRecovery2 service.
     ///
-    /// Note: This should be used with SVR2 only. For SVR1 clients, use ``PinHash/init(pin:salt:)``
+    /// Note: This should be used with SVR2 only. For SVR1 clients, use ``PinHash/init(normalizedPin:salt:)``
     ///
     /// - parameter normalizedPin: An already normalized UTF-8 encoded byte representation of the pin
     /// - parameter username: The Basic Auth username used to authenticate with SVR2