Fix documentation and add support for CI-ing it (#679)

* Fix documentation and add support for CI-ing it

* Fixup license header

Author: Lukasa

Sources/AsyncHTTPClient/AsyncAwait/HTTPClientResponse.swift

@@ -87,7 +87,7 @@ extension HTTPClientResponse {
             self.storage = storage
         }
 
-        /// Accumulates `Body` of ``ByteBuffer``s into a single ``ByteBuffer``.
+        /// Accumulates `Body` of `ByteBuffer`s into a single `ByteBuffer`.
         /// - Parameters:
         ///   - maxBytes: The maximum number of bytes this method is allowed to accumulate
         /// - Throws: `NIOTooManyBytesError` if the the sequence contains more than `maxBytes`.

Sources/AsyncHTTPClient/Docs.docc/index.md

@@ -2,6 +2,8 @@
 
 This package provides simple HTTP Client library built on top of SwiftNIO.
 
+## Overview
+
 This library provides the following:
 - First class support for Swift Concurrency (since version 1.9.0)
 - Asynchronous and non-blocking request methods
@@ -17,7 +19,7 @@ This library provides the following:
 
 ---
 
-## Getting Started
+### Getting Started
 
 #### Adding the dependency
 
@@ -71,13 +73,13 @@ httpClient.get(url: "https://apple.com/").whenComplete { result in
 }
 ```
 
-You should always shut down ``HTTPClient`` instances you created using ``HTTPClient/shutdown()-96ayw()``. Please note that you must not call ``HTTPClient/shutdown()-96ayw()`` before all requests of the HTTP client have finished, or else the in-flight requests will likely fail because their network connections are interrupted.
+You should always shut down ``HTTPClient`` instances you created using ``HTTPClient/shutdown()-9gcpw``. Please note that you must not call ``HTTPClient/shutdown()-9gcpw`` before all requests of the HTTP client have finished, or else the in-flight requests will likely fail because their network connections are interrupted.
 
-### async/await examples
+#### async/await examples
 
 Examples for the async/await API can be found in the [`Examples` folder](https://github.com/swift-server/async-http-client/tree/main/Examples) in the repository.
 
-## Usage guide
+### Usage guide
 
 The default HTTP Method is `GET`. In case you need to have more control over the method, or you want to add headers or body, use the ``HTTPClientRequest`` struct:
 
@@ -134,14 +136,14 @@ httpClient.execute(request: request).whenComplete { result in
 }
 ```
 
-### Redirects following
+#### Redirects following
 Enable follow-redirects behavior using the client configuration:
 ```swift
 let httpClient = HTTPClient(eventLoopGroupProvider: .createNew,
                             configuration: HTTPClient.Configuration(followRedirects: true))
 ```
 
-### Timeouts
+#### Timeouts
 Timeouts (connect and read) can also be set using the client configuration:
 ```swift
 let timeout = HTTPClient.Configuration.Timeout(connect: .seconds(1), read: .seconds(1))
@@ -153,11 +155,11 @@ or on a per-request basis:
 httpClient.execute(request: request, deadline: .now() + .milliseconds(1))
 ```
 
-### Streaming
+#### Streaming
 When dealing with larger amount of data, it's critical to stream the response body instead of aggregating in-memory. 
 The following example demonstrates how to count the number of bytes in a streaming response body:
 
-#### Using Swift Concurrency
+##### Using Swift Concurrency
 ```swift
 let httpClient = HTTPClient(eventLoopGroupProvider: .createNew)
 do {
@@ -189,7 +191,7 @@ do {
 try await httpClient.shutdown()
 ```
 
-#### Using HTTPClientResponseDelegate and SwiftNIO EventLoopFuture
+##### Using HTTPClientResponseDelegate and SwiftNIO EventLoopFuture
 
 ```swift
 import NIOCore
@@ -251,7 +253,7 @@ httpClient.execute(request: request, delegate: delegate).futureResult.whenSucces
 }
 ```
 
-### File downloads
+#### File downloads
 
 Based on the `HTTPClientResponseDelegate` example above you can build more complex delegates,
 the built-in `FileDownloadDelegate` is one of them. It allows streaming the downloaded data
@@ -280,7 +282,7 @@ client.execute(request: request, delegate: delegate).futureResult
     }
 ```
 
-### Unix Domain Socket Paths
+#### Unix Domain Socket Paths
 Connecting to servers bound to socket paths is easy:
 ```swift
 let httpClient = HTTPClient(eventLoopGroupProvider: .createNew)
@@ -314,7 +316,7 @@ let secureSocketPathBasedURL = URL(
 )
 ```
 
-### Disabling HTTP/2
+#### Disabling HTTP/2
 The exclusive use of HTTP/1 is possible by setting ``HTTPClient/Configuration/httpVersion-swift.property`` to ``HTTPClient/Configuration/HTTPVersion-swift.struct/http1Only`` on the ``HTTPClient/Configuration``:
 ```swift
 var configuration = HTTPClient.Configuration()
@@ -325,7 +327,7 @@ let client = HTTPClient(
 )
 ```
 
-## Security
+### Security
 
 AsyncHTTPClient's security process is documented on [GitHub](https://github.com/swift-server/async-http-client/blob/main/SECURITY.md).
 

Sources/AsyncHTTPClient/HTTPClient.swift

@@ -228,7 +228,7 @@ public class HTTPClient {
     /// Shuts down the ``HTTPClient`` and releases its resources.
     ///
     /// - note: You cannot use this method if you sharted the ``HTTPClient`` with
-    ///         ``init(eventLoopGroupProvider: .createNew)`` because that will shut down the ``EventLoopGroup`` the
+    ///         `init(eventLoopGroupProvider: .createNew)` because that will shut down the `EventLoopGroup` the
     ///         returned future would run in.
     public func shutdown() -> EventLoopFuture<Void> {
         switch self.eventLoopGroupProvider {

Sources/AsyncHTTPClient/HTTPHandler.swift

@@ -388,7 +388,7 @@ public final class ResponseAccumulator: HTTPClientResponseDelegate {
     /// until it will abort the request and throw an ``ResponseTooBigError``.
     ///
     /// Default is 2^32.
-    /// - precondition: not allowed to exceed 2^32 because ``ByteBuffer`` can not store more bytes
+    /// - precondition: not allowed to exceed 2^32 because `ByteBuffer` can not store more bytes
     public let maxBodySize: Int
 
     public convenience init(request: HTTPClient.Request) {
@@ -400,7 +400,7 @@ public final class ResponseAccumulator: HTTPClientResponseDelegate {
     ///   - maxBodySize: Maximum size in bytes of the HTTP response body that ``ResponseAccumulator`` will accept
     ///   until it will abort the request and throw an ``ResponseTooBigError``.
     ///   Default is 2^32.
-    /// - precondition: maxBodySize is not allowed to exceed 2^32 because ``ByteBuffer`` can not store more bytes
+    /// - precondition: maxBodySize is not allowed to exceed 2^32 because `ByteBuffer` can not store more bytes
     /// - warning: You can use ``ResponseAccumulator`` for just one request.
     /// If you start another request, you need to initiate another ``ResponseAccumulator``.
     public init(request: HTTPClient.Request, maxBodySize: Int) {

docker/docker-compose.2004.55.yaml

@@ -9,6 +9,9 @@ services:
         ubuntu_version: "focal"
         swift_version: "5.5"
 
+  documentation-check:
+    image: async-http-client:20.04-5.5
+
   test:
     image: async-http-client:20.04-5.5
     command: /bin/bash -xcl "swift test --parallel -Xswiftc -warnings-as-errors $${SANITIZER_ARG-}"

docker/docker-compose.2004.56.yaml

@@ -9,6 +9,9 @@ services:
         ubuntu_version: "focal"
         swift_version: "5.6"
 
+  documentation-check:
+    image: async-http-client:20.04-5.6
+
   test:
     image: async-http-client:20.04-5.6
     environment: []

docker/docker-compose.2204.57.yaml

@@ -9,6 +9,9 @@ services:
         ubuntu_version: "jammy"
         swift_version: "5.7"
 
+  documentation-check:
+    image: async-http-client:22.04-5.7
+
   test:
     image: async-http-client:22.04-5.7
     environment: []

docker/docker-compose.2204.58.yaml

@@ -8,6 +8,9 @@ services:
       args:
         base_image: "swiftlang/swift:nightly-5.8-jammy"
 
+  documentation-check:
+    image: async-http-client:22.04-5.8
+
   test:
     image: async-http-client:22.04-5.8
     environment:

docker/docker-compose.2204.main.yaml

@@ -8,6 +8,9 @@ services:
       args:
         base_image: "swiftlang/swift:nightly-main-jammy"
 
+  documentation-check:
+    image: async-http-client:22.04-main
+
   test:
     image: async-http-client:22.04-main
     environment:

docker/docker-compose.yaml

@@ -26,6 +26,10 @@ services:
     <<: *common
     command: /bin/bash -xcl "./scripts/soundness.sh"
 
+  documentation-check:
+    <<: *common
+    command: /bin/bash -xcl "./scripts/check-docs.sh"
+    
   test:
     <<: *common
     command: /bin/bash -xcl "swift test --parallel -Xswiftc -warnings-as-errors --enable-test-discovery $${SANITIZER_ARG-} $${IMPORT_CHECK_ARG-}"

scripts/check-docs.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+##===----------------------------------------------------------------------===##
+##
+## This source file is part of the AsyncHTTPClient open source project
+##
+## Copyright (c) 2023 Apple Inc. and the AsyncHTTPClient project authors
+## Licensed under Apache License v2.0
+##
+## See LICENSE.txt for license information
+## See CONTRIBUTORS.txt for the list of AsyncHTTPClient project authors
+##
+## SPDX-License-Identifier: Apache-2.0
+##
+##===----------------------------------------------------------------------===##
+
+set -eu
+
+raw_targets=$(sed -E -n -e 's/^.* - documentation_targets: \[(.*)\].*$/\1/p' .spi.yml)
+targets=(${raw_targets//,/ })
+
+for target in "${targets[@]}"; do
+  swift package plugin generate-documentation --target "$target" --warnings-as-errors --analyze --level detailed
+done