From 833ad99c1a8d497609ef7ba103641a7fe82f6c57 Mon Sep 17 00:00:00 2001
From: martintmk <103487740+martintmk@users.noreply.github.com>
Date: Wed, 14 Jun 2023 15:25:00 +0200
Subject: [PATCH] Cleanup Polly.Core README.md (#1298)

---
 src/Polly.Core/README.md | 35 ++++++++++++++++++++---------------
 1 file changed, 20 insertions(+), 15 deletions(-)

diff --git a/src/Polly.Core/README.md b/src/Polly.Core/README.md
index 73df356b3c5..179a33918a8 100644
--- a/src/Polly.Core/README.md
+++ b/src/Polly.Core/README.md
@@ -15,7 +15,7 @@ At the heart of Polly V8 is the [ResilienceStrategy](ResilienceStrategy.cs) clas
 public abstract class ResilienceStrategy
 {
     // the main method that all the others call
-    protected virtual ValueTask<TResult> ExecuteCoreAsync<TResult, TState>(Func<ResilienceContext, TState, ValueTask<TResult>> execution, ResilienceContext context, TState state);
+    protected virtual ValueTask<Outcome<TResult>> ExecuteCoreAsync<TResult, TState>(Func<ResilienceContext, TState, ValueTask<Outcome<TResult>>> execution, ResilienceContext context, TState state);
 
     // convenience methods for various types of user-callbacks
     public void Execute(Action callback);
@@ -76,7 +76,7 @@ public void Execute(Action execute)
         strategy.ExecuteCoreAsync(static (context, state) =>
         {
             state();
-            return new ValueTask<VoidResult>(VoidResult.Instance);
+            return new ValueTask<Outcome<VoidResult>>(new(VoidResult.Instance));
         }, 
         context, 
         execute).GetAwaiter().GetResult();
@@ -109,7 +109,7 @@ internal class DelayStrategy : ResilienceStrategy
     }
 
     protected override async ValueTask<T> ExecuteCoreAsync<T, TState>(
-        Func<ResilienceContext, TState, ValueTask<T>> callback, 
+        Func<ResilienceContext, TState, ValueTask<Outcome<T>>> callback, 
         ResilienceContext context, 
         TState state)
     {
@@ -126,22 +126,17 @@ This way, the responsibility of how to execute method is lifted from the user an
 
 The life of extensibility author is also simplified as they only maintain one implementation of strategy instead of multiple ones. See the duplications in [`Polly.Retry`](https://github.com/App-vNext/Polly/tree/main/src/Polly/Retry).
 
-## Creation of `ResilienceStrategy`
-
-This API exposes [ResilienceStrategyBuilder](Builder/ResilienceStrategyBuilder.cs) that can be used to create the resilience strategy:
+### Generic Resilience Strategy
 
-``` csharp
-public class ResilienceStrategyBuilder
-{
-    // omitted properties for simplicity
+Polly also exposes the sealed `ResilienceStrategy<T>` strategy that is just a simple wrapper over `ResilienceStrategy`. This strategy is used for scenarios when the consumer handles the single result type.
 
-    ResilienceStrategyBuilder AddStrategy(ResilienceStrategy strategy, ResilienceStrategyOptions? options = null);
+## Creation of `ResilienceStrategy`
 
-    ResilienceStrategyBuilder AddStrategy(Func<ResilienceStrategyBuilderContext, ResilienceStrategy> factory, ResilienceStrategyOptions? options = null);
+This API exposes the following builders:
 
-    ResilienceStrategy Build();
-}
-```
+- [ResilienceStrategyBuilder](ResilienceStrategyBuilder.cs): Used to create resilience strategies that can execute all types of callbacks. In general, these strategies only handle exceptions. 
+- [ResilienceStrategyBuilder<T>](ResilienceStrategyBuilder.TResult.cs): Used to create generic resilience strategies that can only execute callbacks that return the same result type.
+- [ResilienceStrategyBuilderBase](ResilienceStrategyBuilderBase.cs): The base class for both builders above. You can use it as a target for strategy extensions that work for both builders above.  
 
 To create a strategy or pipeline of strategies you chain various extensions for `ResilienceStrategyBuilder` followed by the `Build` call:
 
@@ -165,6 +160,16 @@ var resilienceStrategy = new ResilienceStrategyBuilder()
 
 The resilience extensibility is simple. You just expose extensions for `ResilienceStrategyBuilder` that use the `ResilienceStrategyBuilder.AddStrategy` methods.
 
+If you want to create a resilience strategy that works for both generic and non-generic builders you can use `ResilienceStrategyBuilderBase` as a target:
+
+``` csharp
+public static TBuilder AddMyStrategy<TBuilder>(this TBuilder builder)
+    where TBuilder : ResilienceStrategyBuilderBase
+{
+    return builder.AddStrategy(new MyStrategy());
+}
+```
+
 # Resilience Strategy Delegates
 
 Resilience strategies leverage the following delegate types: