Update docs and cleanup some chaos API

docs/chaos/index.md

@@ -7,6 +7,40 @@
 
 ![Simmy](../media/simmy-logo.png)
 
+## Usage
+
+<!-- snippet: chaos-usage -->
+```cs
+var builder = new ResiliencePipelineBuilder<HttpResponseMessage>();
+
+// First, configure regular resilience strategies
+builder
+    .AddConcurrencyLimiter(10, 100)
+    .AddRetry(new())
+    .AddCircuitBreaker(new())
+    .AddTimeout(TimeSpan.FromSeconds(5));
+
+// Finally, configure chaos strategies if you want to inject chaos.
+// These should come after the regular resilience strategies.
+
+// 2% of invocations will be injected with chaos
+const double InjectionRate = 0.02;
+
+builder
+    // Inject a chaos latency to executions
+    .AddChaosLatency(InjectionRate, TimeSpan.FromMinutes(1))
+    // Inject a chaos fault to executions
+    .AddChaosFault(InjectionRate, () => new InvalidOperationException("Injected by chaos strategy!"))
+    // Inject a chaos outcome to executions
+    .AddChaosResult(InjectionRate, () => new HttpResponseMessage(System.Net.HttpStatusCode.InternalServerError))
+    // Inject a chaos behavior to executions
+    .AddChaosBehavior(0.001, () => RestartRedisAsync());
+```
+<!-- endSnippet -->
+
+> [!NOTE]
+> It is usual to place the chaos strategy as the last strategy in the resilience pipeline. By placing the chaos strategies as last, they subvert the usual outbound call at the last minute, substituting their fault or adding extra latency, etc. The existing resilience strategies - further out in the `ResiliencePipeline` - still apply, so you can test how the Polly resilience strategies you have configured handle the chaos/faults injected by Simmy.
+
 ## Motivation
 
 There are a lot of questions when it comes to chaos engineering and making sure that a system is actually ready to face the worst possible scenarios:
@@ -38,10 +72,6 @@ Chaos strategies (or Monkey strategies as we call them) are in essence a [Resili
 | [Latency](latency.md)   | No       | Injects latency into executions before the calls are made.           |
 | [Behavior](behavior.md) | No       | Allows you to inject *any* extra behaviour, before a call is placed. |
 
-## Usage
-
-It is usual to place the chaos strategy as the last strategy in the resilience pipeline. By placing the chaos strategies as last, they subvert the usual outbound call at the last minute, substituting their fault or adding extra latency, etc. The existing resilience strategies - further out in the `ResiliencePipeline` - still apply, so you can test how the Polly resilience strategies you have configured handle the chaos/faults injected by Simmy.
-
 ## Common options across strategies
 
 All the strategies' options implement the [`MonkeyStrategyOptions`](xref:Polly.Simmy.MonkeyStrategyOptions) class as it contains the basic configuration for every chaos strategy.

src/Snippets/Docs/Chaos.Index.cs

@@ -0,0 +1,41 @@
+using System.Net.Http;
+using Polly.Simmy;
+
+namespace Snippets.Docs;
+
+internal static partial class Chaos
+{
+    public static void Usage()
+    {
+        #region chaos-usage
+
+        var builder = new ResiliencePipelineBuilder<HttpResponseMessage>();
+
+        // First, configure regular resilience strategies
+        builder
+            .AddConcurrencyLimiter(10, 100)
+            .AddRetry(new())
+            .AddCircuitBreaker(new())
+            .AddTimeout(TimeSpan.FromSeconds(5));
+
+        // Finally, configure chaos strategies if you want to inject chaos.
+        // These should come after the regular resilience strategies.
+
+        // 2% of invocations will be injected with chaos
+        const double InjectionRate = 0.02;
+
+        builder
+            // Inject a chaos latency to executions
+            .AddChaosLatency(InjectionRate, TimeSpan.FromMinutes(1))
+            // Inject a chaos fault to executions
+            .AddChaosFault(InjectionRate, () => new InvalidOperationException("Injected by chaos strategy!"))
+            // Inject a chaos outcome to executions
+            .AddChaosResult(InjectionRate, () => new HttpResponseMessage(System.Net.HttpStatusCode.InternalServerError))
+            // Inject a chaos behavior to executions
+            .AddChaosBehavior(0.001, () => RestartRedisAsync());
+
+        #endregion
+    }
+
+    private static ValueTask RestartRedisAsync() => ValueTask.CompletedTask;
+}