fix documentation errors (#24)

* add workflow for validating docs using unidoc * fix unidoc errors * fix remaining errors * purge DocC hashes
swift-on-server · Jan 9, 2025 · 5b98959 · 5b98959
1 parent 906270d
commit 5b98959
Show file tree

Hide file tree

Showing 20 changed files with 233 additions and 173 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,8 +1,10 @@
-.DS_Store
-.swiftpm
-.vscode
-.build
-Sources/**/*.html
+/.DS_Store
+/.swiftpm
+/.vscode
+/.build
+/.build.ssgc
+/.ssgc
+/Sources/**/*.html
+/.build.ssgc
+/.index-build
 docc
-.build.ssgc
-.index-build
diff --git a/Package.resolved b/Package.resolved
@@ -1,13 +1,13 @@
 {
-  "originHash" : "f6c66464b7de44086527b7c7cc0d835ea39ea97cad7b0a31a2ce3c82650872f4",
+  "originHash" : "bc7e7da478a806e0f7cbe377f7686d6279b8f12a875ce24603298eac157fefe8",
   "pins" : [
     {
       "identity" : "async-http-client",
       "kind" : "remoteSourceControl",
-      "location" : "https://github.com/swift-server/async-http-client",
+      "location" : "https://github.com/swift-server/async-http-client.git",
       "state" : {
-        "revision" : "e8babad8226b9b3f956a252d5b80e36b0c9d62a9",
-        "version" : "1.22.0"
+        "revision" : "2119f0d9cc1b334e25447fe43d3693c0e60e6234",
+        "version" : "1.24.0"
       }
     },
     {
@@ -24,8 +24,8 @@
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/adam-fowler/compress-nio.git",
       "state" : {
-        "revision" : "a52d3ac5f48820846d34d78d6f59316481e84968",
-        "version" : "1.2.1"
+        "revision" : "459a803a4e38718d94d64f2b31e83f01d934f324",
+        "version" : "1.4.0"
       }
     },
     {
@@ -69,32 +69,41 @@
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/hummingbird-project/hummingbird.git",
       "state" : {
-        "revision" : "6c568da113a7abe712e4a00883a85ff7745d6929",
-        "version" : "2.0.0"
+        "revision" : "7a41c20c25866064f22b2bfa2c8194083e7e1595",
+        "version" : "2.6.1"
+      }
+    },
+    {
+      "identity" : "hummingbird-auth",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/hummingbird-project/hummingbird-auth.git",
+      "state" : {
+        "revision" : "8630a49acca3b38c50e29d61ab263cb7edf0b06d",
+        "version" : "2.0.2"
       }
     },
     {
       "identity" : "hummingbird-websocket",
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/hummingbird-project/hummingbird-websocket.git",
       "state" : {
-        "revision" : "f53e2afe403b225a674fb5d1f0c5830d3991e9dc",
-        "version" : "2.0.0"
+        "revision" : "11b4b5235e03f07511e4bb8e22204d35c5691120",
+        "version" : "2.3.0"
       }
     },
     {
       "identity" : "mongokitten",
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/orlandos-nl/MongoKitten.git",
       "state" : {
-        "revision" : "6654e801833d5dab3c04af065646ba727f9542e9",
-        "version" : "7.9.7"
+        "revision" : "d9a82f57e24018cfa47a4aa359b51e684040871a",
+        "version" : "7.9.8"
       }
     },
     {
       "identity" : "swift-algorithms",
       "kind" : "remoteSourceControl",
-      "location" : "https://github.com/apple/swift-algorithms",
+      "location" : "https://github.com/apple/swift-algorithms.git",
       "state" : {
         "revision" : "f6919dfc309e7f1b56224378b11e28bab5bccc42",
         "version" : "1.2.0"
@@ -103,19 +112,28 @@
     {
       "identity" : "swift-argument-parser",
       "kind" : "remoteSourceControl",
-      "location" : "https://github.com/apple/swift-argument-parser",
+      "location" : "https://github.com/apple/swift-argument-parser.git",
       "state" : {
         "revision" : "41982a3656a71c768319979febd796c6fd111d5c",
         "version" : "1.5.0"
       }
     },
+    {
+      "identity" : "swift-asn1",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-asn1.git",
+      "state" : {
+        "revision" : "7faebca1ea4f9aaf0cda1cef7c43aecd2311ddf6",
+        "version" : "1.3.0"
+      }
+    },
     {
       "identity" : "swift-async-algorithms",
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/apple/swift-async-algorithms.git",
       "state" : {
-        "revision" : "6ae9a051f76b81cc668305ceed5b0e0a7fd93d20",
-        "version" : "1.0.1"
+        "revision" : "4c3ea81f81f0a25d0470188459c6d4bf20cf2f97",
+        "version" : "1.0.3"
       }
     },
     {
@@ -132,35 +150,62 @@
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/apple/swift-collections.git",
       "state" : {
-        "revision" : "9bf03ff58ce34478e66aaee630e491823326fd06",
-        "version" : "1.1.3"
+        "revision" : "671108c96644956dddcd89dd59c203dcdb36cec7",
+        "version" : "1.1.4"
+      }
+    },
+    {
+      "identity" : "swift-crypto",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-crypto.git",
+      "state" : {
+        "revision" : "ff0f781cf7c6a22d52957e50b104f5768b50c779",
+        "version" : "3.10.0"
       }
     },
     {
       "identity" : "swift-distributed-tracing",
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/apple/swift-distributed-tracing.git",
       "state" : {
-        "revision" : "11c756c5c4d7de0eeed8595695cadd7fa107aa19",
-        "version" : "1.1.1"
+        "revision" : "6483d340853a944c96dbcc28b27dd10b6c581703",
+        "version" : "1.1.2"
+      }
+    },
+    {
+      "identity" : "swift-extras-base64",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/swift-extras/swift-extras-base64.git",
+      "state" : {
+        "revision" : "dc8121fdd2b444c97d6b0534e8ad4ddecbe0d5f4",
+        "version" : "1.0.0"
       }
     },
     {
       "identity" : "swift-http-types",
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/apple/swift-http-types.git",
       "state" : {
-        "revision" : "ae67c8178eb46944fd85e4dc6dd970e1f3ed6ccd",
-        "version" : "1.3.0"
+        "revision" : "ef18d829e8b92d731ad27bb81583edd2094d1ce3",
+        "version" : "1.3.1"
+      }
+    },
+    {
+      "identity" : "swift-jobs",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/hummingbird-project/swift-jobs.git",
+      "state" : {
+        "revision" : "6aeb0a179567b944ecf81e1bbfdd474c1ee171f1",
+        "version" : "1.0.0-beta.6"
       }
     },
     {
       "identity" : "swift-log",
       "kind" : "remoteSourceControl",
-      "location" : "https://github.com/apple/swift-log",
+      "location" : "https://github.com/apple/swift-log.git",
       "state" : {
-        "revision" : "9cb486020ebf03bfa5b5df985387a14a98744537",
-        "version" : "1.6.1"
+        "revision" : "96a2f8a0fa41e9e09af4585e2724c4e825410b91",
+        "version" : "1.6.2"
       }
     },
     {
@@ -175,55 +220,55 @@
     {
       "identity" : "swift-mustache",
       "kind" : "remoteSourceControl",
-      "location" : "https://github.com/hummingbird-project/swift-mustache",
+      "location" : "https://github.com/hummingbird-project/swift-mustache.git",
       "state" : {
-        "revision" : "cde358e364ab26f2b72a5f70613cfb0a574de6c9",
-        "version" : "2.0.0-beta.3"
+        "revision" : "9de71fc4d10f0efc0ac758d0acf14e75d39b47b4",
+        "version" : "2.0.0"
       }
     },
     {
       "identity" : "swift-nio",
       "kind" : "remoteSourceControl",
-      "location" : "https://github.com/apple/swift-nio",
+      "location" : "https://github.com/apple/swift-nio.git",
       "state" : {
-        "revision" : "4c4453b489cf76e6b3b0f300aba663eb78182fad",
-        "version" : "2.70.0"
+        "revision" : "dca6594f65308c761a9c409e09fbf35f48d50d34",
+        "version" : "2.77.0"
       }
     },
     {
       "identity" : "swift-nio-extras",
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/apple/swift-nio-extras.git",
       "state" : {
-        "revision" : "d1ead62745cc3269e482f1c51f27608057174379",
-        "version" : "1.24.0"
+        "revision" : "2e9746cfc57554f70b650b021b6ae4738abef3e6",
+        "version" : "1.24.1"
       }
     },
     {
       "identity" : "swift-nio-http2",
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/apple/swift-nio-http2.git",
       "state" : {
-        "revision" : "b5f7062b60e4add1e8c343ba4eb8da2e324b3a94",
-        "version" : "1.34.0"
+        "revision" : "170f4ca06b6a9c57b811293cebcb96e81b661310",
+        "version" : "1.35.0"
       }
     },
     {
       "identity" : "swift-nio-ssl",
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/apple/swift-nio-ssl.git",
       "state" : {
-        "revision" : "7b84abbdcef69cc3be6573ac12440220789dcd69",
-        "version" : "2.27.2"
+        "revision" : "c7e95421334b1068490b5d41314a50e70bab23d1",
+        "version" : "2.29.0"
       }
     },
     {
       "identity" : "swift-nio-transport-services",
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/apple/swift-nio-transport-services.git",
       "state" : {
-        "revision" : "38ac8221dd20674682148d6451367f89c2652980",
-        "version" : "1.21.0"
+        "revision" : "bbd5e63cf949b7db0c9edaf7a21e141c52afe214",
+        "version" : "1.23.0"
       }
     },
     {
@@ -256,19 +301,28 @@
     {
       "identity" : "swift-service-lifecycle",
       "kind" : "remoteSourceControl",
-      "location" : "https://github.com/swift-server/swift-service-lifecycle",
+      "location" : "https://github.com/swift-server/swift-service-lifecycle.git",
       "state" : {
-        "revision" : "24c800fb494fbee6e42bc156dc94232dc08971af",
-        "version" : "2.6.1"
+        "revision" : "c2e97cf6f81510f2d6b4a69453861db65d478560",
+        "version" : "2.6.3"
       }
     },
     {
       "identity" : "swift-system",
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/apple/swift-system.git",
       "state" : {
-        "revision" : "d2ba781702a1d8285419c15ee62fd734a9437ff5",
-        "version" : "1.3.2"
+        "revision" : "c8a44d836fe7913603e246acab7c528c2e780168",
+        "version" : "1.4.0"
+      }
+    },
+    {
+      "identity" : "swift-websocket",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/hummingbird-project/swift-websocket.git",
+      "state" : {
+        "revision" : "b15960a331ad39b3c1ee9e76afc34d951e07803b",
+        "version" : "1.2.1"
       }
     }
   ],

diff --git a/Package.swift b/Package.swift
@@ -11,8 +11,10 @@ let package = Package(
     ],
     dependencies: [
         .package(url: "https://github.com/hummingbird-project/hummingbird.git", from: "2.0.0"),
+        .package(url: "https://github.com/hummingbird-project/hummingbird-auth.git", from: "2.0.2"),
         .package(url: "https://github.com/hummingbird-project/hummingbird-websocket.git", from: "2.0.0"),
         .package(url: "https://github.com/hummingbird-project/swift-mustache.git", from: "2.0.0-beta.3"),
+        .package(url: "https://github.com/hummingbird-project/swift-jobs.git", from: "1.0.0-beta.6"),
         .package(url: "https://github.com/swift-server/async-http-client.git", from: "1.21.1"),
         .package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.5.0"),
         .package(url: "https://github.com/apple/swift-nio.git", from: "2.65.0"),
@@ -32,10 +34,12 @@ let package = Package(
                 .product(name: "HummingbirdRouter", package: "hummingbird"),
                 .product(name: "AsyncHTTPClient", package: "async-http-client"),
                 .product(name: "ArgumentParser", package: "swift-argument-parser"),
+                .product(name: "Jobs", package: "swift-jobs"),
                 .product(name: "NIOCore", package: "swift-nio"),
                 .product(name: "NIOPosix", package: "swift-nio"),
                 .product(name: "Logging", package: "swift-log"),
                 .product(name: "ServiceLifecycle", package: "swift-service-lifecycle"),
+                .product(name: "HummingbirdAuth", package: "hummingbird-auth"),
                 .product(name: "HummingbirdWebSocket", package: "hummingbird-websocket"),
                 .product(name: "HummingbirdWSCompression", package: "hummingbird-websocket"),
                 .product(name: "Mustache", package: "swift-mustache"),

diff --git a/Snippets/advanced-async-sequences.swift b/Snippets/advanced-async-sequences.swift
@@ -207,7 +207,7 @@ extension DelayedElementEmitter {
     }
 }
 // snippet.end
-// snipet.delayedprint
+// snippet.delayedprint
 let delayedEmitter = DelayedElementEmitter(
     elements: [1, 2, 3, 4, 5],
     delay: .seconds(1)

diff --git a/...es/Documentation.docc/2024/advanced-async-sequences/advanced-async-sequences.md b/...es/Documentation.docc/2024/advanced-async-sequences/advanced-async-sequences.md
@@ -21,7 +21,7 @@ When you're using a `for .. in` loop to iterate elements, you're always leveragi
 
 ### IteratorProtocol
 
-Sequence implementations only need to provide one function, the ``Sequence/makeIterator`` function. This function creates an ``IteratorProtocol`` that you implement as well.
+Sequence implementations only need to provide one function, the ``Sequence/makeIterator [requirement]`` function. This function creates an ``IteratorProtocol`` that you implement as well.
 
 _IteratorProtocol_ should be implemented as a `struct`, and has a single function called ``IteratorProtocol/next()``. This _mutating_ function returns the next element in the sequence.
 
@@ -113,9 +113,9 @@ The `downloadState` property is set to `downloading` before parallelising work.
 
 ## Implementing Custom AsyncSequence
 
-You can implement your own ``AsyncSequence`` by implementing the ``AsyncSequence`` protocol. This protocol has two associated types: ``Element`` and ``AsyncIterator``. You'll need to implement the ``AsyncSequence/makeAsyncIterator()`` function and the ``AsyncIteratorProtocol``.
+You can implement your own ``AsyncSequence`` by implementing the ``AsyncSequence`` protocol. This protocol has two associated types: ``AsyncSequence/Element`` and ``AsyncSequence/AsyncIterator``. You'll need to implement the ``AsyncSequence/makeAsyncIterator()`` function and the ``AsyncIteratorProtocol``.
 
-First we'll define our custom ``DelayedElementEmitter`` struct. This struct will emit elements from an array with a delay between each element.
+First we'll define our custom `DelayedElementEmitter` struct. This struct will emit elements from an array with a delay between each element.
 
 @Snippet(path: "site/Snippets/advanced-async-sequences", slice: "delayedelementemitter")
 
@@ -129,7 +129,7 @@ You can now use this custom ``AsyncSequence`` in your code. The following exampl
 
 @Snippet(path: "site/Snippets/advanced-async-sequences", slice: "delayedprint")
 
-Note that our custom ``DelayedElementEmitter`` cannot be iterated upon without a `try` keyword to handle errors. This is because the ``AsyncIteratorProtocol/next()`` function can throw errors due to being marked as `throws`. We can also handle the ``CancellationError``s that ``Task.sleep(for:tolerance:clock:)`` throws in the `next()` function.
+Note that our custom `DelayedElementEmitter` cannot be iterated upon without a `try` keyword to handle errors. This is because the ``AsyncIteratorProtocol/next()`` function can throw errors due to being marked as `throws`. We can also handle the ``CancellationError``s that ``Task.sleep(for:tolerance:clock:)`` throws in the `next()` function.
 
 ```swift
 mutating func next() async -> Element? {
@@ -155,7 +155,7 @@ The ``AsyncIteratorProtocol/next()`` function can be cancelled by the consumer.
 
 It is expected that Async Sequences handle cancellation gracefully as appropriate. In Networking, this could mean cancelling a network request. In a generator, this could mean stopping the generation of new elements through ``AsyncStream.Continuation.finish()``.
 
-To detect a cancellation signal, use ``withTaskCancellationHandler(operation:onCancel:)``. Or when using Swift Service Lifecycle, use ``withTaskCancellationOrGracefulShutdownHandler(operation:onCancelOrGracefulShutdown:)``.
+To detect a cancellation signal, use ``withTaskCancellationHandler(operation:onCancel:isolation:)``. Or when using Swift Service Lifecycle, use ``withTaskCancellationOrGracefulShutdownHandler(isolation:operation:onCancelOrGracefulShutdown:)``.
 
 ## Changes in Swift 6