Updated the documentations in the Website service target.

2026-08-30 08:37:19 +02:00
parent 8a9402e8f1
commit 5a833be33d
7 changed files with 41 additions and 43 deletions
@@ -139,7 +139,7 @@ private func logger(
 /// HTTPS-redirect middleware that bounces requests forwarded over plain HTTP to the canonical origin, the trailing-slash redirect middleware that
 /// collapses each path onto its canonical form, the vary middleware that marks every response as varying on `Accept-Encoding`, the response-compression middleware that compresses responses
 /// larger than `minimumResponseSizeToCompress` when the client advertises support, the localization middleware that negotiates the request's
-/// language from its `Accept-Language` header, the not-found middleware that serves the error page, and the static file middleware that serves the
+/// language from its `Accept-Language` header, the not-found middleware that serves the not-found page, and the static file middleware that serves the
 /// contents of `staticFilesPath` (tagging responses with the given `cacheControl` directives), then adds the `RootController` routes that
 /// render the landing page, and the `HealthController` routes that serve the health check.
 ///
@@ -154,7 +154,7 @@ private func logger(
 ///   - cacheControl: the cache-control directives applied to the served static files.
 ///   - compressionMinResponseSize: the minimum response body size, in bytes, before compression is applied.
 ///   - httpsRedirect: the origin plain-HTTP requests are redirected to, and whether the forwarded-protocol header is trusted.
-///   - rateLimit: the rate limit applied to the subscription endpoint.
+///   - rateLimit: the rate limit configuration, currently applied to no route.
 ///   - securityHeaders: the security headers applied to every response.
 ///   - logLevel: the level the request-logging middleware logs at.
 ///   - probe: the probe consulted by the `HealthController` readiness route.
@@ -186,7 +186,7 @@ package extension ConfigReader {
        )
    }

-    /// The rate limit applied to the subscription endpoint, built from the `rateLimit.*` keys.
+    /// The rate limit built from the `rateLimit.*` keys; the template applies it to no route yet.
    ///
    /// `rateLimit.limit` requests are admitted per client per `rateLimit.window` seconds. When `rateLimit.trustForwardedFor` is set,
    /// clients are keyed by the first `X-Forwarded-For` entry — enable it only behind a reverse proxy that sets the header, since clients can forge it
@@ -25,8 +25,7 @@ struct NotFoundPage {
    /// Creates a not-found page localized to the given locale.
    /// - Parameters:
    ///   - locale: the locale the page content is localized to.
-    ///   - assetVersion: the version token appended to the page's asset URLs, or `nil` (the
-    ///     default) to leave them unversioned.
+    ///   - assetVersion: the version token appended to the page's asset URLs, or `nil` (the default) to leave them unversioned.
    ///   - analytics: the analytics tracker embedded in the document head, or `nil` (the default) to omit it.
    init(
        locale: Locale,
@@ -38,9 +37,10 @@ struct NotFoundPage {
        self.locale = locale
        self.localize = .init(bundle: .module)
    }
+
 }

-// MARK: Page
+// MARK: - Page

 extension NotFoundPage: Page {

@@ -3,7 +3,8 @@ import Infrastructure
 /// A static file shipped with the website service.
 ///
 /// Each constant declares one file stored under the static files root (the `Resources/Static` directory) and served by Hummingbird's
-/// `FileMiddleware` middleware. A file can be available with more than one extension (see ``fileExtensions``), each resolving to its own file.
+/// `FileMiddleware` middleware. A file can be available with more than one extension (see ``fileExtensions``), each resolving to its own file, and
+/// sits in its extension's own folder unless it names a ``folder`` of its own.
 struct StaticFile: Asset {

    // MARK: Properties
@@ -117,10 +117,8 @@ private extension HealthController {

    /// Builds a JSON response carrying the given status and payload.
    ///
-    /// Every response is marked `noindex`. The checks answer `200 OK` to anyone who asks and nothing on the site links to them, so they are
-    /// unlikely to be found — but `robots.txt` allows the whole site, and a path that leaks into a log, a monitor, or an inbound link is crawlable
-    /// on discovery. The header keeps them out of the index even once they are fetched, which a `Disallow` rule would not: that stops the crawl, not
-    /// the indexing, and publishes the paths to everyone reading the file.
+    /// Every response is marked `noindex`: the checks answer `200 OK` to anyone, and `robots.txt` allows the whole site. A `Disallow` rule would
+    /// stop the crawl but not the indexing, and would publish the paths to everyone reading the file.
    /// - Parameters:
    ///   - status: the HTTP status of the response.
    ///   - payload: the JSON body of the response.
@@ -5,10 +5,10 @@ public extension NotFoundMiddleware {

    // MARK: Initializers

-    /// Creates a not-found middleware that renders the website's error page, localized to the module's String Catalog languages.
+    /// Creates a not-found middleware that renders the website's not-found page, localized to the module's String Catalog languages.
    /// - Parameters:
    ///   - assetVersion: the version token appended to the page's asset URLs, or `nil` (the default) to leave them unversioned.
-    ///   - analytics: the analytics tracker the error page embeds, or `nil` (the default) to omit it.
+    ///   - analytics: the analytics tracker the page embeds, or `nil` (the default) to omit the tracker script.
    init(
        assetVersion: String? = nil,
        analytics: Analytics? = nil