Documentation updates (#1630)

- Apply some grammar, spelling and wording changes to the documentation for v8.
- Add links to concepts.

README_V8.md

@@ -299,7 +299,7 @@ new ResiliencePipelineBuilder<UserAvatar>()
         OnFallback = args =>
         {
             // Add extra logic to be executed when the fallback is triggered, such as logging.
-            return default; // returns an empty ValueTask
+            return default; // Returns an empty ValueTask
         }
     });
 ```

docs/advanced/dependency-injection.md

@@ -4,7 +4,7 @@ Starting with version 8, Polly provides features that make the integration of Po
 
 ## Usage
 
-To use the DI functionality, add the `Polly.Extensions` package to your project:
+To use the DI functionality, add the [`Polly.Extensions`](https://www.nuget.org/packages/Polly.Extensions) package to your project:
 
 ```sh
 dotnet add package Polly.Extensions
@@ -234,7 +234,7 @@ Over the years, many developers have used Polly in various ways. Some of these r
 
 ❌ DON'T
 
-Capture `IServiceCollection` inside `AddResiliencePipeline`:
+Capture `IServiceCollection` inside `AddResiliencePipeline()`:
 
 <!-- snippet: di-anti-pattern-1 -->
 ```cs
@@ -261,7 +261,7 @@ This approach builds a new `ServiceProvider` before each retry attempt _unnecess
 
 ✅ DO
 
-Use another overload of `AddResiliencePipeline` which allows access to `IServiceProvider`:
+Use another overload of `AddResiliencePipeline()` which allows access to `IServiceProvider`:
 
 <!-- snippet: di-pattern-1 -->
 ```cs

docs/advanced/performance.md

@@ -37,7 +37,7 @@ await resiliencePipeline.ExecuteAsync(
     cancellationToken);
 
 // This approach uses a static lambda, avoiding allocations.
-// The "userId" is stored as state, and the lambda reads it.
+// The "userId" is stored as state, and the lambda consumes it.
 await resiliencePipeline.ExecuteAsync(
     static (state, cancellationToken) => GetMemberAsync(state, cancellationToken),
     userId,
@@ -62,7 +62,7 @@ new ResiliencePipelineBuilder()
     })
     .Build();
 
-// For optimal performance, it's recommended to use switch expressions over PredicateBuilder.
+// For optimal performance, it's recommended to use switch expressions instead of PredicateBuilder.
 new ResiliencePipelineBuilder()
     .AddRetry(new()
     {
@@ -147,7 +147,7 @@ public class MyApi
 
     public async Task UpdateData(CancellationToken cancellationToken)
     {
-        // Get or create and cache the pipeline for subsequent use.
+        // Get or create the pipeline, and then cache it for subsequent use.
         // Choose a sufficiently unique key to prevent collisions.
         var pipeline = _registry.GetOrAddPipeline("my-app.my-api", builder =>
         {

docs/advanced/telemetry.md

@@ -99,7 +99,7 @@ builder.AddRetry(new RetryStrategyOptions
 ```
 <!-- endSnippet -->
 
-These values are subsequently reflected in the following metering instruments exposed by the Polly:
+These values are subsequently reflected in the following metering instruments exposed by Polly:
 
 ### Instrument: `resilience.polly.strategy.events`
 

docs/advanced/testing.md

@@ -1,12 +1,12 @@
 # Testing
 
-This document explains how to test Polly’s resilience pipelines. You should not test how the resilience pipelines operate internally, but rather test your own settings or custom delegates.
+This document explains how to test Polly's resilience pipelines. You should not test how the resilience pipelines operate internally, but rather test your own settings or custom delegates.
 
 To make the testing process simpler, Polly offers the [`Polly.Testing`](https://www.nuget.org/packages/Polly.Testing/) package. This package has a range of APIs designed to help you test the setup and combination of resilience pipelines in your user code.
 
 ## Usage
 
-Begin by adding the `Polly.Testing` package to your test project:
+Begin by adding the [`Polly.Testing`](https://www.nuget.org/packages/Polly.Testing) package to your test project:
 
 ```sh
 dotnet add package Polly.Testing

docs/extensibility/index.md

@@ -18,8 +18,8 @@ Regardless of whether the strategy is reactive or proactive, every new resilienc
 The strategy options contain properties of following types:
 
 - **Common types**: Such as `int`, `bool`, `TimeSpan`, etc.
-- **Delegates**: For example when strategy need to raise an event, or generate a value. In general, the delegates should by asynchronous.
-- **Arguments**: Used by the delegates to pass the information to consumers.
+- **Delegates**: For example when a strategy needs to raise an event, or generate a value. In general, the delegates should by asynchronous.
+- **Arguments**: Used by the delegates to pass the information to their consumers.
 
 ## Delegates
 
@@ -45,10 +45,10 @@ Recommended signatures for these delegates are:
 - `Func<Args<TResult>, ValueTask<TValue>>` (Reactive)
 - `Func<Args, ValueTask<TValue>>` (Proactive)
 
-These delegates accept either `Args` or `Args<TResult>` arguments, which encapsulate event information. Note that all these delegates are asynchronous and return a `ValueTask`. Learn more about [arguments](#arguments) in the sections bellow.
+These delegates accept either `Args` or `Args<TResult>` arguments, which encapsulate event information. Note that all these delegates are asynchronous and return a `ValueTask`. Learn more about [arguments](#arguments) in the sections below.
 
 > [!NOTE]
-> When setting up delegates, consider using the `ResilienceContext.ContinueOnCapturedContext` property if your user code interacts with a synchronization context (as in asynchronous UI applications like Windows Forms or WPF).
+> When setting up delegates, consider using the `ResilienceContext.ContinueOnCapturedContext` property if your user code interacts with a synchronization context (such as in asynchronous UI applications like Windows Forms or WPF).
 
 ### How to use delegates
 
@@ -87,7 +87,7 @@ new ResiliencePipelineBuilder<string>()
 
 ## Arguments
 
-Arguments are used by individual delegate types to flow information to the consumer. Arguments should always have an `Arguments` suffix and include a `Context` property. Using arguments boosts the extensibility and maintainability of the API, as adding new members becomes a non-breaking change.  For proactive strategies, the arguments structure might resemble:
+Arguments are used by individual delegate types to flow information to the consumer. Arguments should always have an `Arguments` suffix and include a `Context` property. Using arguments boosts the extensibility and maintainability of the API, as adding new members becomes a non-breaking change.  For proactive strategies, the arguments structure might resemble the following:
 
 <!-- snippet: ext-proactive-args -->
 ```cs
@@ -114,7 +114,7 @@ public readonly struct ThresholdExceededArguments
 
 ## Implementing a resilience strategy
 
-To understand the details of implementing a strategy, use the links below:
+To find out more details about implementing a strategy, follow the links below:
 
 - [Proactive strategy](proactive-strategy.md): Explains how to implement a proactive resilience strategy.
 - [Reactive strategy](reactive-strategy.md): Explains how to implement a reactive resilience strategy.

docs/extensibility/proactive-strategy.md

@@ -85,7 +85,7 @@ public readonly struct ThresholdExceededArguments
 ```
 <!-- endSnippet -->
 
-Arguments should always have an `Arguments` suffix and include a `Context` property. Using arguments boosts the extensibility and maintainability of the API, as adding new members becomes a non-breaking change. The `ThresholdExceededArguments` provides details about the actual execution time and threshold, allowing listeners to respond to this event or supply a custom callback for such situations.
+Arguments should always have an `Arguments` suffix and include a `Context` property. Using arguments boosts the extensibility and maintainability of the API, as adding new members becomes a non-breaking change. The `ThresholdExceededArguments` provides details about the actual execution time and threshold, allowing consumers to respond to this event or supply a custom callback for such situations.
 
 ## Options
 
@@ -125,7 +125,7 @@ So far, we've covered:
 - The public `TimingStrategyOptions` and its associated arguments.
 - The proactive strategy implementation named `TimingResilienceStrategy`.
 
-The final step is to integrate these components by adding new extensions for both `ResiliencePipelineBuilder` and `ResiliencePipelineBuilder<T>`. Since both builders inherit from the same base class, we can introduce a single extension for `ResiliencePipelineBuilderBase` to serve both.
+The final step is to integrate these components with each other by adding new extensions for both `ResiliencePipelineBuilder` and `ResiliencePipelineBuilder<T>`. Since both builders inherit from the same base class, we can introduce a single extension for `ResiliencePipelineBuilderBase` to serve both.
 
 <!-- snippet: ext-proactive-extensions -->
 ```cs
@@ -143,7 +143,7 @@ public static class TimingResilienceStrategyBuilderExtensions
             context =>
             {
                 // The "context" provides various properties for the strategy's use.
-                // In this case, we simply use the "Telemetry" and pass it to the strategy.
+                // In this case, we simply use the "Telemetry" property and pass it to the strategy.
                 // The Threshold and ThresholdExceeded values are sourced from the options.
                 var strategy = new TimingResilienceStrategy(
                     options.Threshold!.Value,
@@ -180,7 +180,7 @@ var pipeline = new ResiliencePipelineBuilder()
 
 ## Resources
 
-For further understanding of proactive resilience strategies, consider exploring these resources:
+For further information on proactive resilience strategies, consider exploring these resources:
 
 - [Timing strategy sample](https://github.com/App-vNext/Polly/tree/main/samples/Extensibility/Proactive): A practical example from this guide.
 - [Timeout resilience strategy](https://github.com/App-vNext/Polly/tree/main/src/Polly.Core/Timeout): Discover the built-in timeout resilience strategy implementation.

docs/extensibility/reactive-strategy.md

@@ -51,7 +51,7 @@ internal sealed class ResultReportingResilienceStrategy<T> : ResilienceStrategy<
 ```
 <!-- endSnippet -->
 
-Reactive strategies use the `ShouldHandle` predicate to decide whether to handle the outcome of a user callback. The convention is to name the predicate's arguments using the `<StrategyName>PredicateArguments` pattern and return a `ValueTask<bool>`. Here, we use `ResultReportingPredicateArguments<TResult>`:
+Reactive strategies use the `ShouldHandle` predicate to decide whether to handle the outcome of a user callback. The convention is to name the predicate's arguments using the `{StrategyName}PredicateArguments` pattern and return a `ValueTask<bool>`. Here, we use `ResultReportingPredicateArguments<TResult>`:
 
 <!-- snippet: ext-reactive-predicate-args -->
 ```cs
@@ -101,7 +101,7 @@ Using arguments in callbacks supports a more maintainable and extensible API.
 
 In the previous section, we implemented the `ResultReportingResilienceStrategy<T>`. Now, we need to integrate it with Polly and its public API.
 
-Define the public `ResultReportingStrategyOptions<TResult>` to configure our strategy:
+Define the public `ResultReportingStrategyOptions<TResult>` class to configure our strategy:
 
 <!-- snippet: ext-reactive-options -->
 ```cs
@@ -123,7 +123,7 @@ public class ResultReportingStrategyOptions<TResult> : ResilienceStrategyOptions
     // This illustrates an event delegate. Note that the arguments struct carries the same name as the delegate but with an "Arguments" suffix.
     // The event follows the async convention and must be set by the user.
     //
-    // The [Required] enforces the consumer to specify this property, used when some properties do not have sensible defaults and are required.
+    // The [Required] attribute enforces the consumer to specify this property, used when some properties do not have sensible defaults and are required.
     [Required]
     public Func<OnReportResultArguments<TResult>, ValueTask>? OnReportResult { get; set; }
 }
@@ -142,7 +142,7 @@ public class ResultReportingStrategyOptions : ResultReportingStrategyOptions<obj
 ```
 <!-- endSnippet -->
 
-Using options as a public contract helps us ensure flexibility with consumers. By adopting this method, you can effortlessly introduce new members without inducing breaking changes and maintain consistent validation.
+Using options as a public contract helps us ensure flexibility with consumers. By adopting this method, you can introduce new members with ease without introducing breaking changes and maintain consistent validation.
 
 ## Extensions
 
@@ -161,13 +161,13 @@ public static class ResultReportingResilienceStrategyBuilderExtensions
     // Extensions should return the builder to support a fluent API.
     public static ResiliencePipelineBuilder<TResult> AddResultReporting<TResult>(this ResiliencePipelineBuilder<TResult> builder, ResultReportingStrategyOptions<TResult> options)
     {
-        // Incorporate the strategy using the AddStrategy method. This method receives a factory delegate
+        // Incorporate the strategy using the AddStrategy() method. This method receives a factory delegate
         // and automatically checks the options.
         return builder.AddStrategy(
             context =>
             {
                 // The "context" offers various properties for the strategy to use.
-                // Here, we simply use the "Telemetry" and hand it over to the strategy.
+                // Here, we simply use the "Telemetry" property and hand it over to the strategy.
                 // The ShouldHandle and OnReportResult values come from the options.
                 var strategy = new ResultReportingResilienceStrategy<TResult>(
                     options.ShouldHandle,
@@ -243,7 +243,7 @@ new ResiliencePipelineBuilder()
 
 ## Resources
 
-For further understanding of reactive resilience strategies, consider exploring these resources:
+For further information about reactive resilience strategies, consider exploring these resources:
 
 - [Result reporting strategy sample](https://github.com/App-vNext/Polly/tree/main/samples/Extensibility/Reactive): A practical example from this guide.
 - [Retry resilience strategy](https://github.com/App-vNext/Polly/tree/main/src/Polly.Core/Retry): Discover the built-in retry resilience strategy implementation.