Refactors based on review

docs/pipelines/index.md

@@ -137,18 +137,21 @@ Use `ExecuteOutcomeAsync(...)` in high-performance scenarios where you wish to a
 
 ## Diagrams
 
-### Variant one
+### Sequence diagram for a pipeline with retry and timeout
 
-<!-- snippet: resilience-pipeline-diagram-variant-1 -->
+<!-- snippet: resilience-pipeline-diagram-retry-timeout -->
 ```cs
+// Let's create the following pipeline:
+// the inner strategy is a timeout,
+// the outer is a retry which is timeout-aware.
 ResiliencePipeline pipeline = new ResiliencePipelineBuilder()
     .AddRetry(new() { ShouldHandle = new PredicateBuilder().Handle<TimeoutRejectedException>() }) // outer
     .AddTimeout(TimeSpan.FromSeconds(1)) // inner
     .Build();
 ```
 <!-- endSnippet -->
 
-Lets suppose that the first request takes too long bust the second is super fast.
+Let's suppose that the first request takes too long but the second is fast enough.
 
 ```mermaid
 sequenceDiagram
@@ -193,18 +196,21 @@ sequenceDiagram
     P->>C: Returns result
 ```
 
-### Variant two
+### Sequence diagram for a pipeline with timeout and retry
 
-<!-- snippet: resilience-pipeline-diagram-variant-2 -->
+<!-- snippet: resilience-pipeline-diagram-timeout-retry -->
 ```cs
+// Let's create the following pipeline:
+// the inner strategy is a retry,
+// the outer is a timeout which overarches all retry attempts.
 ResiliencePipeline pipeline = new ResiliencePipelineBuilder()
     .AddTimeout(TimeSpan.FromSeconds(10)) // outer
     .AddRetry(new()) // inner
     .Build();
 ```
 <!-- endSnippet -->
 
-Lets suppose that the 1st and the 2nd requests are failing. The 3rd requested is not awaited since the overarching timeout elapsed.
+Let's suppose that the first and the second requests are failing. The third request is not awaited since the overarching timeout elapsed.
 
 ```mermaid
 sequenceDiagram
@@ -253,10 +259,14 @@ sequenceDiagram
     P->>C: Propagates exception
 ```
 
-### Variant three
+### Sequence diagram for a pipeline with timeout, retry and timeout
 
-<!-- snippet: resilience-pipeline-diagram-variant-3 -->
+<!-- snippet: resilience-pipeline-diagram-timeout-retry-timeout -->
 ```cs
+// Let's create the following pipeline:
+// the inner most strategy is a timeout (per attempt),
+// the middle one is a retry which is timeout-aware,
+// the outer most is a timeout which overarches all retry attempts.
 ResiliencePipeline pipeline = new ResiliencePipelineBuilder()
     .AddTimeout(TimeSpan.FromSeconds(10)) // outer most
     .AddRetry(new() { ShouldHandle = new PredicateBuilder().Handle<TimeoutRejectedException>() })
@@ -265,7 +275,7 @@ ResiliencePipeline pipeline = new ResiliencePipelineBuilder()
 ```
 <!-- endSnippet -->
 
-Lets suppose that the 1st request fails; the 2nd requests takes too long; and the 3rd requested is not awaited since the overarching timeout elapsed.
+Let's suppose that the first request fails and the second takes too long. The third request is not awaited since the overarching timeout elapsed.
 
 ```mermaid
 sequenceDiagram

src/Snippets/Docs/ResiliencePipelines.cs

@@ -83,29 +83,39 @@ public static void ConfigureMyPipelines(IServiceCollection services)
 
     #endregion
 
-    public static void ResiliencePipelinesDiagramVariantOne()
+    public static void ResiliencePipelinesDiagramRetryTimeout()
     {
-        #region resilience-pipeline-diagram-variant-1
+        #region resilience-pipeline-diagram-retry-timeout
+        // Let's create the following pipeline:
+        // the inner strategy is a timeout,
+        // the outer is a retry which is timeout-aware.
         ResiliencePipeline pipeline = new ResiliencePipelineBuilder()
             .AddRetry(new() { ShouldHandle = new PredicateBuilder().Handle<TimeoutRejectedException>() }) // outer
             .AddTimeout(TimeSpan.FromSeconds(1)) // inner
             .Build();
         #endregion
     }
 
-    public static void ResiliencePipelinesDiagramVariantTwo()
+    public static void ResiliencePipelinesDiagramTimeoutRetry()
     {
-        #region resilience-pipeline-diagram-variant-2
+        #region resilience-pipeline-diagram-timeout-retry
+        // Let's create the following pipeline:
+        // the inner strategy is a retry,
+        // the outer is a timeout which overarches all retry attempts.
         ResiliencePipeline pipeline = new ResiliencePipelineBuilder()
             .AddTimeout(TimeSpan.FromSeconds(10)) // outer
             .AddRetry(new()) // inner
             .Build();
         #endregion
     }
 
-    public static void ResiliencePipelinesDiagramVariantThree()
+    public static void ResiliencePipelinesDiagramTimeoutRetryTimeout()
     {
-        #region resilience-pipeline-diagram-variant-3
+        #region resilience-pipeline-diagram-timeout-retry-timeout
+        // Let's create the following pipeline:
+        // the inner most strategy is a timeout (per attempt),
+        // the middle one is a retry which is timeout-aware,
+        // the outer most is a timeout which overarches all retry attempts.
         ResiliencePipeline pipeline = new ResiliencePipelineBuilder()
             .AddTimeout(TimeSpan.FromSeconds(10)) // outer most
             .AddRetry(new() { ShouldHandle = new PredicateBuilder().Handle<TimeoutRejectedException>() })