Add more detail to the Overview section of the documentation landing …

…page.

README.md

@@ -15,7 +15,23 @@ HTTP libraries like `Foundation` pass the response through to the caller without
 
 The module works with any HTTP library that is compatible with Swift’s [standard HTTP request and response types](https://github.com/apple/swift-http-types). The module can be used on its own in code that directly uses an HTTP library, or the module can be used as a building block by higher-level networking libraries.
 
-## Example Usage
+### Representing an HTTP Application Failure
+
+After interpreting an HTTP response as a success or a failure, there needs to be a way to represent a failure. In Swift, failures are represented by a type that conforms to the `Error` protocol. Therefore, the module exposes an `HTTPApplicationError` type to represent a failure.
+
+### Interpreting HTTP Responses
+
+The module extends `HTTPResponse` with a `throwIfFailed` method that interprets the response as a success or failure. The method throws `HTTPApplicationError` if the response is interpreted as a failure.
+
+Some HTTP servers add additional details about a failure to the response body. The `throwIfFailed` method allows for the response body to be deserialized and attached to the error so that the additional failure details can be accessed later.
+
+### Retrying HTTP Requests
+
+The module extends `HTTPRequest` to add conformance to [`RetryableRequest`](https://fumoboy007.github.io/swift-retry/documentation/retry/retryablerequest), which is a protocol from the [`swift-retry`](https://swiftpackageindex.com/fumoboy007/swift-retry) package that adds safe retry methods to the type. The safe retry methods enforce that the HTTP request is [idempotent](https://httpwg.org/specs/rfc9110.html#idempotent.methods).
+
+The retry method implementations automatically choose a [`RecoveryAction`](https://fumoboy007.github.io/swift-retry/documentation/retry/recoveryaction) for `HTTPApplicationError` using HTTP-specific information including whether the failure is transient and the value of the [`Retry-After`](https://httpwg.org/specs/rfc9110.html#field.retry-after) header, if present.
+
+## Example Usage With `URLSession`
 
 ```swift
 import Foundation

Sources/HTTPErrorHandling/HTTPErrorHandling.docc/HTTPErrorHandling.md

@@ -10,13 +10,29 @@ HTTP libraries like `Foundation` pass the response through to the caller without
 
 The module works with any HTTP library that is compatible with Swift’s [standard HTTP request and response types](https://github.com/apple/swift-http-types). The module can be used on its own in code that directly uses an HTTP library, or the module can be used as a building block by higher-level networking libraries.
 
+### Representing an HTTP Application Failure
+
+After interpreting an HTTP response as a success or a failure, there needs to be a way to represent a failure. In Swift, failures are represented by a type that conforms to the `Error` protocol. Therefore, the module exposes an ``HTTPApplicationError`` type to represent a failure.
+
+### Interpreting HTTP Responses
+
+The module extends `HTTPResponse` with a ``HTTPTypes/HTTPResponse/throwIfFailed(successStatuses:transientFailureStatuses:)`` method that interprets the response as a success or failure. The method throws ``HTTPApplicationError`` if the response is interpreted as a failure.
+
+Some HTTP servers add additional details about a failure to the response body. The ``HTTPTypes/HTTPResponse/throwIfFailed(successStatuses:transientFailureStatuses:makeResponseBody:)`` method allows for the response body to be deserialized and attached to the error so that the additional failure details can be accessed later.
+
+### Retrying HTTP Requests
+
+The module extends `HTTPRequest` to add conformance to [`RetryableRequest`](https://fumoboy007.github.io/swift-retry/documentation/retry/retryablerequest), which is a protocol from the [`swift-retry`](https://swiftpackageindex.com/fumoboy007/swift-retry) package that adds safe retry methods to the type. The safe retry methods enforce that the HTTP request is [idempotent](https://httpwg.org/specs/rfc9110.html#idempotent.methods).
+
+The retry method implementations automatically choose a [`RecoveryAction`](https://fumoboy007.github.io/swift-retry/documentation/retry/recoveryaction) for ``HTTPApplicationError`` using HTTP-specific information including whether the failure is transient and the value of the [`Retry-After`](https://httpwg.org/specs/rfc9110.html#field.retry-after) header, if present.
+
 ## Topics
 
 ### Examples
 
-- <doc:Interpreting-HTTP-Responses>
-- <doc:Retrying-HTTP-Requests>
-- <doc:Interoperability-With-Popular-HTTP-Libraries>
+- <doc:Examples-of-Interpreting-HTTP-Responses>
+- <doc:Examples-of-Retrying-HTTP-Requests>
+- <doc:Examples-of-Interoperability-With-Popular-HTTP-Libraries>
 
 ### Representing an HTTP Application Failure
 

Sources/HTTPErrorHandling/Retry/HTTPRequest+RetryableRequest.swift

@@ -25,17 +25,19 @@ import Retry
 
 /// Adds `RetryableRequest` conformance to `HTTPRequest`.
 ///
-/// The `RetryableRequest` conformance adds safe retry methods to `HTTPRequest`.
+/// The [`RetryableRequest`](https://fumoboy007.github.io/swift-retry/documentation/retry/retryablerequest)
+/// conformance adds safe retry methods to `HTTPRequest`.
 ///
 /// - Important: The retry methods accept a closure that attempts the request. The closure must interpret the response
 ///    and throw ``HTTPApplicationError`` when the response represents a failure. Calling
 ///    ``HTTPTypes/HTTPResponse/throwIfFailed(successStatuses:transientFailureStatuses:)``
 ///    is a convenient way to do so.
 ///
 /// The `recoverFromFailure` closure is not called when the failure is due to ``HTTPApplicationError``. The
-/// retry method implementations automatically choose a recovery action for ``HTTPApplicationError`` using
-/// HTTP-specific information including whether the error is transient and the value of the `Retry-After` header,
-/// if present.
+/// retry method implementations automatically choose a
+/// [`RecoveryAction`](https://fumoboy007.github.io/swift-retry/documentation/retry/recoveryaction)
+/// for ``HTTPApplicationError`` using HTTP-specific information including whether the failure is transient and the
+/// value of the [`Retry-After`](https://httpwg.org/specs/rfc9110.html#field.retry-after) header, if present.
 ///
 /// - SeeAlso: [`Retry`](https://fumoboy007.github.io/swift-retry/documentation/retry/)
 extension HTTPRequest: RetryableRequest {