Documentation updates

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()
     {

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`
 

src/Polly.Core/Retry/RetryStrategyOptions.TResult.cs

@@ -79,8 +79,8 @@ public class RetryStrategyOptions<TResult> : ResilienceStrategyOptions
     /// Gets or sets the maximum delay between retries.
     /// </summary>
     /// <remarks>
-    /// This property is used to cap maximum delay between retries. It is useful when you want to limit the maximum delay after certain
-    /// number of between retries when it could reach a unreasonably high values, especially if <see cref="DelayBackoffType.Exponential"/> backoff is used.
+    /// This property is used to cap the maximum delay between retries. It is useful when you want to limit the maximum delay after a certain
+    /// number of retries when it could reach a unreasonably high values, especially if <see cref="DelayBackoffType.Exponential"/> backoff is used.
     /// If not specified, the delay is not capped. This property is ignored for delays generated by <see cref="DelayGenerator"/>.
     /// </remarks>
     /// <value>

src/Snippets/Docs/Migration.Policies.cs

@@ -15,15 +15,15 @@ public static async Task Policies()
         ISyncPolicy syncPolicy = Policy.Handle<Exception>().WaitAndRetry(3, _ => TimeSpan.FromSeconds(1));
         syncPolicy.Execute(() =>
         {
-            // your code here
+            // Your code here
         });
 
         // Create and use the IAsyncPolicy
         IAsyncPolicy asyncPolicy = Policy.Handle<Exception>().WaitAndRetryAsync(3, _ => TimeSpan.FromSeconds(1));
         await asyncPolicy.ExecuteAsync(
             async cancellationToken =>
             {
-                // your code here
+                // Your code here
             },
             cancellationToken);
 
@@ -34,7 +34,7 @@ await asyncPolicy.ExecuteAsync(
 
         syncPolicyT.Execute(() =>
         {
-            // your code here
+            // Your code here
             return GetResponse();
         });
 
@@ -45,7 +45,7 @@ await asyncPolicy.ExecuteAsync(
         await asyncPolicyT.ExecuteAsync(
             async cancellationToken =>
             {
-                // your code here
+                // Your code here
                 return await GetResponseAsync(cancellationToken);
             },
             cancellationToken);
@@ -71,26 +71,26 @@ public static async Task Strategies()
                 MaxRetryAttempts = 3,
                 BackoffType = DelayBackoffType.Constant
             })
-            .Build(); // After all necessary strategies are added, call build to create the pipeline.
+            .Build(); // After all necessary strategies are added, call Build() to create the pipeline.
 
         // Synchronous execution
         pipeline.Execute(() =>
         {
-            // your code here
+            // Your code here
         });
 
         // Asynchronous execution is also supported with the same pipeline instance
         await pipeline.ExecuteAsync(static async cancellationToken =>
         {
-            // your code here
+            // Your code here
         },
         cancellationToken);
 
         // Create and use the ResiliencePipeline<T>.
         //
         // Building of generic resilience pipeline is very similar to non-generic one.
         // Notice the use of generic RetryStrategyOptions<HttpResponseMessage> to configure the strategy
-        // As opposed to providing the arguments into the method.
+        // as opposed to providing the arguments into the method.
         ResiliencePipeline<HttpResponseMessage> pipelineT = new ResiliencePipelineBuilder<HttpResponseMessage>()
             .AddRetry(new RetryStrategyOptions<HttpResponseMessage>
             {
@@ -106,14 +106,14 @@ await pipeline.ExecuteAsync(static async cancellationToken =>
         // Synchronous execution
         pipelineT.Execute(() =>
         {
-            // your code here
+            // Your code here
             return GetResponse();
         });
 
         // Asynchronous execution
         await pipelineT.ExecuteAsync(static async cancellationToken =>
         {
-            // your code here
+            // Your code here
             return await GetResponseAsync(cancellationToken);
         },
         cancellationToken);

src/Snippets/Docs/Migration.Registry.cs

@@ -24,7 +24,7 @@ public static void Registry_V7()
         registry.AddOrUpdate(
             "my-key",
             Policy.Timeout(TimeSpan.FromSeconds(10)),
-            (key, old) => Policy.Timeout(TimeSpan.FromSeconds(10)));
+            (key, previous) => Policy.Timeout(TimeSpan.FromSeconds(10)));
 
         #endregion
     }

src/Snippets/Docs/Migration.Retry.cs

@@ -82,7 +82,7 @@ public static void Retry_V8()
         new ResiliencePipelineBuilder().AddRetry(new RetryStrategyOptions
         {
             // PredicateBuilder is used to simplify the initialization of predicates.
-            // Its API should be familiar to v7 way of configuring what exceptions to handle.
+            // Its API should be familiar to the v7 way of configuring what exceptions to handle.
             ShouldHandle = new PredicateBuilder().Handle<SomeExceptionType>(),
             MaxRetryAttempts = 1,
             // To disable waiting between retries, set the Delay property to TimeSpan.Zero.
@@ -177,7 +177,7 @@ public static void Retry_V8()
         })
         .Build();
 
-        // The same as above, but using the switch expressions for max performance.
+        // The same as above, but using the switch expressions for best performance.
         new ResiliencePipelineBuilder<HttpResponseMessage>().AddRetry(new RetryStrategyOptions<HttpResponseMessage>
         {
             // Determine what results to retry using switch expressions.

src/Snippets/Docs/Migration.Wrap.cs

@@ -10,7 +10,7 @@ public static void PolicyWrap_V7()
 
         IAsyncPolicy timeoutPolicy = Policy.TimeoutAsync(TimeSpan.FromSeconds(3));
 
-        // Wrap the policies. Tne policies are executed in the following order:
+        // Wrap the policies. The policies are executed in the following order (i.e. Last-In-First-Out):
         // 1. Retry
         // 2. Timeout
         IAsyncPolicy wrappedPolicy = Policy.WrapAsync(timeoutPolicy, retryPolicy);
@@ -22,7 +22,7 @@ public static void PolicyWrap_V8()
     {
         #region migration-policy-wrap-v8
 
-        // The "PolicyWrap" is integrated directly. Strategies are executed in the same order as they were added:
+        // The "PolicyWrap" is integrated directly. Strategies are executed in the same order as they were added (i.e. First-In-First-Out):
         // 1. Retry
         // 2. Timeout
         ResiliencePipeline pipeline = new ResiliencePipelineBuilder()

src/Snippets/Docs/Performance.cs

@@ -22,7 +22,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,
@@ -46,7 +46,7 @@ public static async Task SwitchExpressions()
             })
             .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()
             {

src/Snippets/README.md

@@ -19,7 +19,7 @@ public static void MySnippet()
 {
     #region my-snippet
 
-    // your code here
+    // Your code here
 
     #endregion
 }