Use Docc for documentation #613
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Motivation Documentation is nice, and we can help support users by providing useful clear docs. Modifications Add Docc to 5.6 and later builds Make sure symbol references work Add overview docs Result Nice rendering docs
Lukasa
added
the
needs-no-version-bump
FranzBusch
approved these changes
Aug 9, 2022
| @@ -16,12 +16,21 @@ | |||
| import NIOCore | |||
| import NIOHTTP1 | |||
|
|
|||
| /// A representation of a HTTP request for the Swift Concurrency HTTPClient API. | |||
There was a problem hiding this comment.
Suggested change
| /// A representation of a HTTP request for the Swift Concurrency HTTPClient API. | |
| /// A representation of an HTTP request for the Swift Concurrency HTTPClient API. |
| @available(macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0, *) | ||
| public struct HTTPClientRequest { | ||
| /// The request URL, including scheme and hostname. |
There was a problem hiding this comment.
Should this also include the port?
| @@ -34,6 +43,10 @@ public struct HTTPClientRequest { | |||
|
|
|||
| @available(macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0, *) | |||
| extension HTTPClientRequest { | |||
| /// A HTTP request body. | |||
There was a problem hiding this comment.
Suggested change
| /// A HTTP request body. | |
| /// An HTTP request body. |
| @@ -54,10 +67,20 @@ extension HTTPClientRequest { | |||
|
|
|||
| @available(macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0, *) | |||
| extension HTTPClientRequest.Body { | |||
| /// Create a ``HTTPClientRequest/Body-swift.struct`` from a `ByteBuffer`. | |||
There was a problem hiding this comment.
Suggested change
| /// Create a ``HTTPClientRequest/Body-swift.struct`` from a `ByteBuffer`. | |
| /// Create an ``HTTPClientRequest/Body-swift.struct`` from a `ByteBuffer`. |
| public static func bytes(_ byteBuffer: ByteBuffer) -> Self { | ||
| self.init(.byteBuffer(byteBuffer)) | ||
| } | ||
|
|
||
| /// Create a ``HTTPClientRequest/Body-swift.struct`` from a `RandomAccessCollection` of bytes. |
There was a problem hiding this comment.
Suggested change
| /// Create a ``HTTPClientRequest/Body-swift.struct`` from a `RandomAccessCollection` of bytes. | |
| /// Create an ``HTTPClientRequest/Body-swift.struct`` from a `RandomAccessCollection` of bytes. |
| public var body: Body | ||
|
|
||
| /// A representation of the response body for a HTTP response. | ||
| /// | ||
| /// The body is streamed in as an `AsyncSequence` of `ByteBuffer`, where each `ByteBuffer` contains |
There was a problem hiding this comment.
Unsure about this one
Suggested change
| /// The body is streamed in as an `AsyncSequence` of `ByteBuffer`, where each `ByteBuffer` contains | |
| /// The body is streamed as an `AsyncSequence` of `ByteBuffer`, where each `ByteBuffer` contains |
| @@ -65,6 +65,9 @@ let globalRequestID = ManagedAtomic(0) | |||
| /// try client.syncShutdown() | |||
| /// ``` | |||
| public class HTTPClient { | |||
| /// The `EventLoopGroup` in use by this `HTTPClient`. | |||
There was a problem hiding this comment.
Suggested change
| /// The `EventLoopGroup` in use by this `HTTPClient`. | |
| /// The `EventLoopGroup` in use by this ``HTTPClient``. |
| @@ -97,7 +99,7 @@ extension HTTPClient { | |||
| } | |||
| } | |||
|
|
|||
| /// Represent HTTP request. | |||
| /// Represents a HTTP request. | |||
There was a problem hiding this comment.
Suggested change
| /// Represents a HTTP request. | |
| /// Represents an HTTP request. |
| @@ -226,7 +228,7 @@ extension HTTPClient { | |||
| } | |||
| } | |||
|
|
|||
| /// Represent HTTP response. | |||
| /// Represents a HTTP response. | |||
There was a problem hiding this comment.
Suggested change
| /// Represents a HTTP response. | |
| /// Represents an HTTP response. |
Sources/AsyncHTTPClient/Utils.swift
Outdated
| @@ -14,6 +14,10 @@ | |||
|
|
|||
| import NIOCore | |||
|
|
|||
| /// A ``HTTPClientResponseDelegate`` that wraps a callback. | |||
There was a problem hiding this comment.
Suggested change
| /// A ``HTTPClientResponseDelegate`` that wraps a callback. | |
| /// An ``HTTPClientResponseDelegate`` that wraps a callback. |
dnadoba
approved these changes
Aug 9, 2022
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Motivation
Documentation is nice, and we can help support users by providing useful
clear docs.
Modifications
Add Docc to 5.6 and later builds
Make sure symbol references work
Add overview docs
Result
Nice rendering docs