Add more detail to the Overview section of the documentation landing page.

Author: fumoboy007

README.md

@@ -7,13 +7,6 @@ Retries in Swift with sensible defaults and powerful flexibility.
 ![MIT License](https://img.shields.io/github/license/fumoboy007/swift-retry)
 ![Automated Tests Workflow Status](https://img.shields.io/github/actions/workflow/status/fumoboy007/swift-retry/tests.yml?event=push&label=tests)
 
-## Features
-
-- Designed for [Swift Concurrency](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/concurrency/).
-- Sensible default retry behavior.
-- Flexible enough for any use case.
-- Comprehensive tests and documentation.
-
 ## Basic Usage
 
 ```swift
@@ -22,4 +15,24 @@ try await retry {
 }
 ```
 
-See the [documentation](https://fumoboy007.github.io/swift-retry/documentation/retry/) for examples of more sophisticated use cases.
+See the [documentation](https://fumoboy007.github.io/swift-retry/documentation/retry/) for examples of more advanced use cases.
+
+## Overview
+
+### Designed for Swift Concurrency
+
+The `retry` function is an `async` function that runs the given `async` closure repeatedly until it succeeds or until the failure is no longer retryable. The function sleeps in between attempts while respecting task cancellation.
+
+### Sensible Defaults
+
+The library uses similar defaults as [Amazon Web Services](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html) and [Google Cloud](https://github.com/googleapis/gax-go/blob/465d35f180e8dc8b01979d09c780a10c41f15136/v2/call_option.go#L181-L205).
+
+An important but often overlooked default is the choice of backoff algorithm, which determines how long to sleep in between attempts. This library chooses an [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff) algorithm by default, which is suitable for most use cases. Most retry use cases involve a resource, such as a server, with potentially many clients where an exponential backoff algorithm would be ideal to avoid [DDoSing the resource](https://cloud.google.com/blog/products/gcp/how-to-avoid-a-self-inflicted-ddos-attack-cre-life-lessons).
+
+### Powerful Flexibility
+
+The API provides several customization points to accommodate any use case:
+- Retries can be selectively enabled or disabled for specific error cases by providing a custom `shouldRetry` closure. Retries can also be selectively enabled or disabled for specific code paths by wrapping thrown errors with `Retryable` or `NotRetryable`. 
+- The `RetryConfiguration` type encapsulates the retry behavior so that it can be reused across multiple call sites without duplicating code.
+- The `Backoff` type represents the choice of algorithm that will be used to determine how long to sleep in between attempts. It has built-in support for common algorithms but can be initialized with a custom `BackoffAlgorithm` implementation if needed.
+- The clock that is used to sleep in between attempts can be replaced. For example, one might use a fake `Clock` implementation in automated tests to ensure the tests are deterministic and efficient.

Sources/Retry/Backoff/Backoff.swift

@@ -26,8 +26,8 @@ public struct Backoff<ClockType: Clock> {
 
    /// The default algorithm, which is suitable for most use cases.
    ///
-   /// This algorithm is an exponential backoff algorithm. The specific choice of algorithm is an implementation
-   /// detail, which may change in the future.
+   /// This algorithm is an [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff) algorithm.
+   /// The specific choice of algorithm is an implementation detail, which may change in the future.
    ///
    /// - Parameters:
    ///    - baseDelay: A duration that all delays will be based on. For example, in a simple exponential
@@ -43,8 +43,8 @@ public struct Backoff<ClockType: Clock> {
 
    /// Exponential backoff with “full jitter”.
    ///
-   /// This algorithm is used by [AWS](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html#feature-retry-behavior-sdk-compat)
-   /// and [Google Cloud](https://github.com/googleapis/gax-go/blob/465d35f180e8dc8b01979d09c780a10c41f15136/v2/call_option.go#L181-L205),
+   /// This algorithm is used by [AWS](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html) and
+   /// [Google Cloud](https://github.com/googleapis/gax-go/blob/465d35f180e8dc8b01979d09c780a10c41f15136/v2/call_option.go#L181-L205),
    /// among others. The advantages and disadvantages of the algorithm are detailed in a [blog post](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/)
    /// by AWS.
    ///
@@ -69,7 +69,7 @@ public struct Backoff<ClockType: Clock> {
    ///
    /// - Warning: This algorithm should only be used as an optimization for a small set of use cases.
    ///    Most retry use cases involve a resource, such as a server, with potentially many clients where an
-   ///    exponential backoff algorithm would be ideal to avoid [DDoSing the server](https://cloud.google.com/blog/products/gcp/how-to-avoid-a-self-inflicted-ddos-attack-cre-life-lessons).
+   ///    exponential backoff algorithm would be ideal to avoid [DDoSing the resource](https://cloud.google.com/blog/products/gcp/how-to-avoid-a-self-inflicted-ddos-attack-cre-life-lessons).
    ///    The constant delay algorithm should only be used in cases where there is no possibility of a DDoS.
    ///
    /// - Parameter delay: The constant duration to sleep in between attempts.

Sources/Retry/Retry.docc/Retry.md

@@ -4,9 +4,23 @@ Retries with sensible defaults and powerful flexibility.
 
 ## Overview
 
-- Designed for [Swift Concurrency](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/concurrency/).
-- Sensible default retry behavior.
-- Flexible enough for any use case.
+### Designed for Swift Concurrency
+
+The ``retry(maxAttempts:backoff:appleLogger:logger:operation:shouldRetry:)`` function is an `async` function that runs the given `async` closure repeatedly until it succeeds or until the failure is no longer retryable. The function sleeps in between attempts while respecting task cancellation.
+
+### Sensible Defaults
+
+The library uses similar defaults as [Amazon Web Services](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html) and [Google Cloud](https://github.com/googleapis/gax-go/blob/465d35f180e8dc8b01979d09c780a10c41f15136/v2/call_option.go#L181-L205).
+
+An important but often overlooked default is the choice of backoff algorithm, which determines how long to sleep in between attempts. This library chooses an [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff) algorithm by default, which is suitable for most use cases. Most retry use cases involve a resource, such as a server, with potentially many clients where an exponential backoff algorithm would be ideal to avoid [DDoSing the resource](https://cloud.google.com/blog/products/gcp/how-to-avoid-a-self-inflicted-ddos-attack-cre-life-lessons).
+
+### Powerful Flexibility
+
+The API provides several customization points to accommodate any use case:
+- Retries can be selectively enabled or disabled for specific error cases by providing a custom ``RetryConfiguration/shouldRetry`` closure. Retries can also be selectively enabled or disabled for specific code paths by wrapping thrown errors with ``Retryable`` or ``NotRetryable``. 
+- The ``RetryConfiguration`` type encapsulates the retry behavior so that it can be reused across multiple call sites without duplicating code.
+- The ``Backoff`` type represents the choice of algorithm that will be used to determine how long to sleep in between attempts. It has built-in support for common algorithms but can be initialized with a custom ``BackoffAlgorithm`` implementation if needed.
+- The ``RetryConfiguration/clock`` that is used to sleep in between attempts can be replaced. For example, one might use a fake `Clock` implementation in automated tests to ensure the tests are deterministic and efficient.
 
 ## Topics