Use Docc for documentation

Package.swift

@@ -1,4 +1,4 @@
-// swift-tools-version:5.4
+// swift-tools-version:5.6
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the AsyncHTTPClient open source project
@@ -28,6 +28,7 @@ let package = Package(
         .package(url: "https://github.com/apple/swift-nio-transport-services.git", from: "1.11.4"),
         .package(url: "https://github.com/apple/swift-log.git", from: "1.4.0"),
         .package(url: "https://github.com/apple/swift-atomics.git", from: "1.0.2"),
+        .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
     ],
     targets: [
         .target(name: "CAsyncHTTPClient"),

Package@swift-5.4.swift

@@ -0,0 +1,74 @@
+// swift-tools-version:5.4
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the AsyncHTTPClient open source project
+//
+// Copyright (c) 2018-2019 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
+//
+//===----------------------------------------------------------------------===//
+
+import PackageDescription
+
+let package = Package(
+    name: "async-http-client",
+    products: [
+        .library(name: "AsyncHTTPClient", targets: ["AsyncHTTPClient"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-nio.git", from: "2.38.0"),
+        .package(url: "https://github.com/apple/swift-nio-ssl.git", from: "2.14.1"),
+        .package(url: "https://github.com/apple/swift-nio-http2.git", from: "1.19.0"),
+        .package(url: "https://github.com/apple/swift-nio-extras.git", from: "1.10.0"),
+        .package(url: "https://github.com/apple/swift-nio-transport-services.git", from: "1.11.4"),
+        .package(url: "https://github.com/apple/swift-log.git", from: "1.4.0"),
+        .package(url: "https://github.com/apple/swift-atomics.git", from: "1.0.2"),
+    ],
+    targets: [
+        .target(name: "CAsyncHTTPClient"),
+        .target(
+            name: "AsyncHTTPClient",
+            dependencies: [
+                .target(name: "CAsyncHTTPClient"),
+                .product(name: "NIO", package: "swift-nio"),
+                .product(name: "NIOCore", package: "swift-nio"),
+                .product(name: "NIOPosix", package: "swift-nio"),
+                .product(name: "NIOHTTP1", package: "swift-nio"),
+                .product(name: "NIOConcurrencyHelpers", package: "swift-nio"),
+                .product(name: "NIOFoundationCompat", package: "swift-nio"),
+                .product(name: "NIOHTTP2", package: "swift-nio-http2"),
+                .product(name: "NIOSSL", package: "swift-nio-ssl"),
+                .product(name: "NIOHTTPCompression", package: "swift-nio-extras"),
+                .product(name: "NIOSOCKS", package: "swift-nio-extras"),
+                .product(name: "NIOTransportServices", package: "swift-nio-transport-services"),
+                .product(name: "Logging", package: "swift-log"),
+                .product(name: "Atomics", package: "swift-atomics"),
+            ]
+        ),
+        .testTarget(
+            name: "AsyncHTTPClientTests",
+            dependencies: [
+                .target(name: "AsyncHTTPClient"),
+                .product(name: "NIOCore", package: "swift-nio"),
+                .product(name: "NIOConcurrencyHelpers", package: "swift-nio"),
+                .product(name: "NIOEmbedded", package: "swift-nio"),
+                .product(name: "NIOFoundationCompat", package: "swift-nio"),
+                .product(name: "NIOTestUtils", package: "swift-nio"),
+                .product(name: "NIOSSL", package: "swift-nio-ssl"),
+                .product(name: "NIOHTTP2", package: "swift-nio-http2"),
+                .product(name: "NIOSOCKS", package: "swift-nio-extras"),
+                .product(name: "Logging", package: "swift-log"),
+                .product(name: "Atomics", package: "swift-atomics"),
+            ],
+            resources: [
+                .copy("Resources/self_signed_cert.pem"),
+                .copy("Resources/self_signed_key.pem"),
+            ]
+        ),
+    ]
+)

Package@swift-5.5.swift

@@ -0,0 +1,74 @@
+// swift-tools-version:5.4
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the AsyncHTTPClient open source project
+//
+// Copyright (c) 2018-2019 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
+//
+//===----------------------------------------------------------------------===//
+
+import PackageDescription
+
+let package = Package(
+    name: "async-http-client",
+    products: [
+        .library(name: "AsyncHTTPClient", targets: ["AsyncHTTPClient"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-nio.git", from: "2.38.0"),
+        .package(url: "https://github.com/apple/swift-nio-ssl.git", from: "2.14.1"),
+        .package(url: "https://github.com/apple/swift-nio-http2.git", from: "1.19.0"),
+        .package(url: "https://github.com/apple/swift-nio-extras.git", from: "1.10.0"),
+        .package(url: "https://github.com/apple/swift-nio-transport-services.git", from: "1.11.4"),
+        .package(url: "https://github.com/apple/swift-log.git", from: "1.4.0"),
+        .package(url: "https://github.com/apple/swift-atomics.git", from: "1.0.2"),
+    ],
+    targets: [
+        .target(name: "CAsyncHTTPClient"),
+        .target(
+            name: "AsyncHTTPClient",
+            dependencies: [
+                .target(name: "CAsyncHTTPClient"),
+                .product(name: "NIO", package: "swift-nio"),
+                .product(name: "NIOCore", package: "swift-nio"),
+                .product(name: "NIOPosix", package: "swift-nio"),
+                .product(name: "NIOHTTP1", package: "swift-nio"),
+                .product(name: "NIOConcurrencyHelpers", package: "swift-nio"),
+                .product(name: "NIOFoundationCompat", package: "swift-nio"),
+                .product(name: "NIOHTTP2", package: "swift-nio-http2"),
+                .product(name: "NIOSSL", package: "swift-nio-ssl"),
+                .product(name: "NIOHTTPCompression", package: "swift-nio-extras"),
+                .product(name: "NIOSOCKS", package: "swift-nio-extras"),
+                .product(name: "NIOTransportServices", package: "swift-nio-transport-services"),
+                .product(name: "Logging", package: "swift-log"),
+                .product(name: "Atomics", package: "swift-atomics"),
+            ]
+        ),
+        .testTarget(
+            name: "AsyncHTTPClientTests",
+            dependencies: [
+                .target(name: "AsyncHTTPClient"),
+                .product(name: "NIOCore", package: "swift-nio"),
+                .product(name: "NIOConcurrencyHelpers", package: "swift-nio"),
+                .product(name: "NIOEmbedded", package: "swift-nio"),
+                .product(name: "NIOFoundationCompat", package: "swift-nio"),
+                .product(name: "NIOTestUtils", package: "swift-nio"),
+                .product(name: "NIOSSL", package: "swift-nio-ssl"),
+                .product(name: "NIOHTTP2", package: "swift-nio-http2"),
+                .product(name: "NIOSOCKS", package: "swift-nio-extras"),
+                .product(name: "Logging", package: "swift-log"),
+                .product(name: "Atomics", package: "swift-atomics"),
+            ],
+            resources: [
+                .copy("Resources/self_signed_cert.pem"),
+                .copy("Resources/self_signed_key.pem"),
+            ]
+        ),
+    ]
+)

Sources/AsyncHTTPClient/AsyncAwait/HTTPClientRequest.swift

@@ -16,12 +16,21 @@
 import NIOCore
 import NIOHTTP1
 
+/// A representation of an HTTP request for the Swift Concurrency HTTPClient API.
+///
+/// This object is similar to ``HTTPClient/Request``, but used for the Swift Concurrency API.
 @available(macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0, *)
 public struct HTTPClientRequest {
+    /// The request URL, including scheme, hostname, and optionally port.
     public var url: String
+
+    /// The request method.
     public var method: HTTPMethod
+
+    /// The request headers.
     public var headers: HTTPHeaders
 
+    /// The request body, if any.
     public var body: Body?
 
     public init(url: String) {
@@ -34,6 +43,10 @@ public struct HTTPClientRequest {
 
 @available(macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0, *)
 extension HTTPClientRequest {
+    /// An HTTP request body.
+    ///
+    /// This object encapsulates the difference between streamed HTTP request bodies and those bodies that
+    /// are already entirely in memory.
     public struct Body {
         @usableFromInline
         internal enum Mode {
@@ -54,10 +67,20 @@ extension HTTPClientRequest {
 
 @available(macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0, *)
 extension HTTPClientRequest.Body {
+    /// Create an ``HTTPClientRequest/Body-swift.struct`` from a `ByteBuffer`.
+    ///
+    /// - parameter byteBuffer: The bytes of the body.
     public static func bytes(_ byteBuffer: ByteBuffer) -> Self {
         self.init(.byteBuffer(byteBuffer))
     }
 
+    /// Create an ``HTTPClientRequest/Body-swift.struct`` from a `RandomAccessCollection` of bytes.
+    ///
+    /// This construction will flatten the bytes into a `ByteBuffer`. As a result, the peak memory
+    /// usage of this construction will be double the size of the original collection. The construction
+    /// of the `ByteBuffer` will be delayed until it's needed.
+    ///
+    /// - parameter bytes: The bytes of the request body.
     @inlinable
     public static func bytes<Bytes: RandomAccessCollection>(
         _ bytes: Bytes
@@ -75,6 +98,23 @@ extension HTTPClientRequest.Body {
         })
     }
 
+    /// Create an ``HTTPClientRequest/Body-swift.struct`` from a `Sequence` of bytes.
+    ///
+    /// This construction will flatten the bytes into a `ByteBuffer`. As a result, the peak memory
+    /// usage of this construction will be double the size of the original collection. The construction
+    /// of the `ByteBuffer` will be delayed until it's needed.
+    ///
+    /// Unlike ``bytes(_:)-1uns7``, this construction does not assume that the body can be replayed. As a result,
+    /// if a redirect is encountered that would need us to replay the request body, the redirect will instead
+    /// not be followed. Prefer ``bytes(_:)-1uns7`` wherever possible.
+    ///
+    /// Caution should be taken with this method to ensure that the `length` is correct. Incorrect lengths
+    /// will cause unnecessary runtime failures. Setting `length` to ``Length/unknown`` will trigger the upload
+    /// to use `chunked` `Transfer-Encoding`, while using ``Length/known(_:)`` will use `Content-Length`.
+    ///
+    /// - parameters:
+    ///     - bytes: The bytes of the request body.
+    ///     - length: The length of the request body.
     @inlinable
     public static func bytes<Bytes: Sequence>(
         _ bytes: Bytes,
@@ -93,6 +133,19 @@ extension HTTPClientRequest.Body {
         })
     }
 
+    /// Create an ``HTTPClientRequest/Body-swift.struct`` from a `Collection` of bytes.
+    ///
+    /// This construction will flatten the bytes into a `ByteBuffer`. As a result, the peak memory
+    /// usage of this construction will be double the size of the original collection. The construction
+    /// of the `ByteBuffer` will be delayed until it's needed.
+    ///
+    /// Caution should be taken with this method to ensure that the `length` is correct. Incorrect lengths
+    /// will cause unnecessary runtime failures. Setting `length` to ``Length/unknown`` will trigger the upload
+    /// to use `chunked` `Transfer-Encoding`, while using ``Length/known(_:)`` will use `Content-Length`.
+    ///
+    /// - parameters:
+    ///     - bytes: The bytes of the request body.
+    ///     - length: The length of the request body.
     @inlinable
     public static func bytes<Bytes: Collection>(
         _ bytes: Bytes,
@@ -111,6 +164,17 @@ extension HTTPClientRequest.Body {
         })
     }
 
+    /// Create an ``HTTPClientRequest/Body-swift.struct`` from an `AsyncSequence` of `ByteBuffer`s.
+    ///
+    /// This construction will stream the upload one `ByteBuffer` at a time.
+    ///
+    /// Caution should be taken with this method to ensure that the `length` is correct. Incorrect lengths
+    /// will cause unnecessary runtime failures. Setting `length` to ``Length/unknown`` will trigger the upload
+    /// to use `chunked` `Transfer-Encoding`, while using ``Length/known(_:)`` will use `Content-Length`.
+    ///
+    /// - parameters:
+    ///     - sequenceOfBytes: The bytes of the request body.
+    ///     - length: The length of the request body.
     @inlinable
     public static func stream<SequenceOfBytes: AsyncSequence>(
         _ sequenceOfBytes: SequenceOfBytes,
@@ -123,6 +187,19 @@ extension HTTPClientRequest.Body {
         return body
     }
 
+    /// Create an ``HTTPClientRequest/Body-swift.struct`` from an `AsyncSequence` of bytes.
+    ///
+    /// This construction will consume 1kB chunks from the `Bytes` and send them at once. This optimizes for
+    /// `AsyncSequence`s where larger chunks are buffered up and available without actually suspending, such
+    /// as those provided by `FileHandle`.
+    ///
+    /// Caution should be taken with this method to ensure that the `length` is correct. Incorrect lengths
+    /// will cause unnecessary runtime failures. Setting `length` to ``Length/unknown`` will trigger the upload
+    /// to use `chunked` `Transfer-Encoding`, while using ``Length/known(_:)`` will use `Content-Length`.
+    ///
+    /// - parameters:
+    ///     - bytes: The bytes of the request body.
+    ///     - length: The length of the request body.
     @inlinable
     public static func stream<Bytes: AsyncSequence>(
         _ bytes: Bytes,
@@ -157,10 +234,12 @@ extension Optional where Wrapped == HTTPClientRequest.Body {
 
 @available(macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0, *)
 extension HTTPClientRequest.Body {
+    /// The length of a HTTP request body.
     public struct Length {
-        /// size of the request body is not known before starting the request
+        /// The size of the request body is not known before starting the request
         public static let unknown: Self = .init(storage: .unknown)
-        /// size of the request body is fixed and exactly `count` bytes
+
+        /// The size of the request body is known and exactly `count` bytes
         public static func known(_ count: Int) -> Self {
             .init(storage: .known(count))
         }

Sources/AsyncHTTPClient/AsyncAwait/HTTPClientResponse.swift

@@ -16,13 +16,28 @@
 import NIOCore
 import NIOHTTP1
 
+/// A representation of an HTTP response for the Swift Concurrency HTTPClient API.
+///
+/// This object is similar to ``HTTPClient/Response``, but used for the Swift Concurrency API.
 @available(macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0, *)
 public struct HTTPClientResponse {
+    /// The HTTP version on which the response was received.
     public var version: HTTPVersion
+
+    /// The HTTP status for this response.
     public var status: HTTPResponseStatus
+
+    /// The HTTP headers of this response.
     public var headers: HTTPHeaders
+
+    /// The body of this HTTP response.
     public var body: Body
 
+    /// A representation of the response body for an HTTP response.
+    ///
+    /// The body is streamed as an `AsyncSequence` of `ByteBuffer`, where each `ByteBuffer` contains
+    /// an arbitrarily large chunk of data. The boundaries between `ByteBuffer` objects in the sequence
+    /// are entirely synthetic and have no semantic meaning.
     public struct Body {
         private let bag: Transaction
         private let reference: ResponseRef