Update docs. (#1413)

Author: martintmk

src/Polly.Core/CircuitBreaker/AdvancedCircuitBreakerStrategyOptions.TResult.cs

@@ -27,31 +27,27 @@ public class AdvancedCircuitBreakerStrategyOptions<TResult> : CircuitBreakerStra
     /// </summary>
     /// <remarks>
     /// A number between zero and one (inclusive) e.g. 0.5 represents breaking if 50% or more of actions result in a handled failure.
-    /// <para>
-    /// A ratio number higher than 0, up to 1.
-    /// Defaults to 0.1 (i.e. 10%).
-    /// </para>
     /// </remarks>
+    /// <value>A ratio number higher than 0, up to 1. The default value is 0.1 (i.e. 10%).</value>
     [Range(0, 1.0)]
     public double FailureThreshold { get; set; } = CircuitBreakerConstants.DefaultAdvancedFailureThreshold;
 
     /// <summary>
     /// Gets or sets the minimum throughput: this many actions or more must pass through the circuit in the time-slice,
     /// for statistics to be considered significant and the circuit-breaker to come into action.
     /// </summary>
-    /// <remarks>
-    /// Value must be 2 or greater.
-    /// Defaults to 100.
-    /// </remarks>
+    /// <value>
+    /// The default value is 0.1 (i.e. 10%). The value must be 2 or greater.
+    /// </value>
     [Range(CircuitBreakerConstants.MinimumValidThroughput, int.MaxValue)]
     public int MinimumThroughput { get; set; } = CircuitBreakerConstants.DefaultMinimumThroughput;
 
     /// <summary>
     /// Gets or sets the duration of the sampling over which failure ratios are assessed.
     /// </summary>
-    /// <remarks>
-    /// Value must be greater than 0.5 seconds. Defaults to 30 seconds.
-    /// </remarks>
+    /// <value>
+    /// The default value is 30 seconds. Value must be greater than 0.5 seconds.
+    /// </value>
     [Range(typeof(TimeSpan), "00:00:00.500", "1.00:00:00")]
     public TimeSpan SamplingDuration { get; set; } = CircuitBreakerConstants.DefaultSamplingDuration;
 }

src/Polly.Core/CircuitBreaker/CircuitBreakerStrategyOptions.cs

@@ -26,20 +26,19 @@ public abstract class CircuitBreakerStrategyOptions<TResult> : ResilienceStrateg
     /// <summary>
     /// Gets or sets the duration of break the circuit will stay open before resetting.
     /// </summary>
-    /// <remarks>
-    /// Value must be greater than 0.5 seconds.
-    /// Defaults to 5 seconds.
-    /// </remarks>
+    /// <value>
+    /// The default value is 5 seconds. Value must be greater than 0.5 seconds.
+    /// </value>
     [Range(typeof(TimeSpan), "00:00:00.500", "1.00:00:00")]
     public TimeSpan BreakDuration { get; set; } = CircuitBreakerConstants.DefaultBreakDuration;
 
     /// <summary>
     /// Gets or sets the predicates for the circuit breaker.
     /// </summary>
-    /// <remarks>
-    /// Defaults to a delegate that handles circuit breaker on any exception except <see cref="OperationCanceledException"/>.
+    /// <value>
+    /// The default value is a predicate that handles circuit breaker on any exception except <see cref="OperationCanceledException"/>.
     /// This property is required.
-    /// </remarks>
+    /// </value>
     [Required]
     public Func<OutcomeArguments<TResult, CircuitBreakerPredicateArguments>, ValueTask<bool>> ShouldHandle { get; set; } = DefaultPredicates<CircuitBreakerPredicateArguments, TResult>.HandleOutcome;
 
@@ -55,10 +54,8 @@ public abstract class CircuitBreakerStrategyOptions<TResult> : ResilienceStrateg
     /// However, the invocation order of the <see cref="OnOpened"/>, <see cref="OnClosed"/>, and <see cref="OnHalfOpened"/> events is always
     /// maintained to ensure the correct sequence of state transitions.
     /// </para>
-    /// <para>
-    /// Defaults to <see langword="null"/>.
-    /// </para>
     /// </remarks>
+    /// <value>The default value is <see langword="null"/>.</value>
     public Func<OutcomeArguments<TResult, OnCircuitClosedArguments>, ValueTask>? OnClosed { get; set; }
 
     /// <summary>
@@ -73,10 +70,8 @@ public abstract class CircuitBreakerStrategyOptions<TResult> : ResilienceStrateg
     /// However, the invocation order of the <see cref="OnOpened"/>, <see cref="OnClosed"/>, and <see cref="OnHalfOpened"/> events is always
     /// maintained to ensure the correct sequence of state transitions.
     /// </para>
-    /// <para>
-    /// Defaults to <see langword="null"/>.
-    /// </para>
     /// </remarks>
+    /// <value>The default value is <see langword="null"/>.</value>
     public Func<OutcomeArguments<TResult, OnCircuitOpenedArguments>, ValueTask>? OnOpened { get; set; }
 
     /// <summary>
@@ -91,26 +86,20 @@ public abstract class CircuitBreakerStrategyOptions<TResult> : ResilienceStrateg
     /// However, the invocation order of the <see cref="OnOpened"/>, <see cref="OnClosed"/>, and <see cref="OnHalfOpened"/> events is always
     /// maintained to ensure the correct sequence of state transitions.
     /// </para>
-    /// <para>
-    /// Defaults to <see langword="null"/>.
-    /// </para>
     /// </remarks>
+    /// <value>The default value is <see langword="null"/>.</value>
     public Func<OnCircuitHalfOpenedArguments, ValueTask>? OnHalfOpened { get; set; }
 
     /// <summary>
     /// Gets or sets the manual control for the circuit breaker.
     /// </summary>
-    /// <remarks>
-    /// Defaults to <see langword="null"/>.
-    /// </remarks>
+    /// <value>The default value is <see langword="null"/>.</value>
     public CircuitBreakerManualControl? ManualControl { get; set; }
 
     /// <summary>
     /// Gets or sets the state provider for the circuit breaker.
     /// </summary>
-    /// <remarks>
-    /// Defaults to <see langword="null"/>.
-    /// </remarks>
+    /// <value>The default value is <see langword="null"/>.</value>
     public CircuitBreakerStateProvider? StateProvider { get; set; }
 }
 

src/Polly.Core/CircuitBreaker/SimpleCircuitBreakerStrategyOptions.TResult.cs

@@ -23,9 +23,9 @@ public class SimpleCircuitBreakerStrategyOptions<TResult> : CircuitBreakerStrate
     /// <summary>
     /// Gets or sets the number of the outcome failures handled by <see cref="CircuitBreakerStrategyOptions{TResult}.ShouldHandle"/> before opening the circuit.
     /// </summary>
-    /// <remarks>
-    /// Must be greater than 0. Defaults to 100.
-    /// </remarks>
+    /// <value>
+    /// The default value is 100. Must be greater than 0.
+    /// </value>
     [Range(1, int.MaxValue)]
     public int FailureThreshold { get; set; } = CircuitBreakerConstants.DefaultFailureThreshold;
 }

src/Polly.Core/Fallback/FallbackStrategyOptions.TResult.cs

@@ -17,28 +17,27 @@ public class FallbackStrategyOptions<TResult> : ResilienceStrategyOptions
     /// <summary>
     /// Gets or sets the outcome predicate for determining whether a fallback should be executed.
     /// </summary>
-    /// <remarks>
-    /// Defaults to a delegate that hedges on any exception except <see cref="OperationCanceledException"/>.
-    /// This property is required.
-    /// </remarks>
+    /// <value>
+    /// The default value is a predicate that fallbacks on any exception except <see cref="OperationCanceledException"/>. This property is required.
+    /// </value>
     [Required]
     public Func<OutcomeArguments<TResult, FallbackPredicateArguments>, ValueTask<bool>> ShouldHandle { get; set; } = DefaultPredicates<FallbackPredicateArguments, TResult>.HandleOutcome;
 
     /// <summary>
     /// Gets or sets the fallback action to be executed when the <see cref="ShouldHandle"/> predicate evaluates as true.
     /// </summary>
-    /// <remarks>
-    /// This property is required. Defaults to <see langword="null"/>.
-    /// </remarks>
+    /// <value>
+    /// The default value is <see langword="null"/>. This property is required.
+    /// </value>
     [Required]
     public Func<OutcomeArguments<TResult, FallbackPredicateArguments>, ValueTask<Outcome<TResult>>>? FallbackAction { get; set; }
 
     /// <summary>
     /// Gets or sets the outcome event instance responsible for triggering fallback events.
     /// </summary>
-    /// <remarks>
-    /// Defaults to <see langword="null"/> instance.
-    /// </remarks>
+    /// <value>
+    /// The default value is <see langword="null"/> instance.
+    /// </value>
     public Func<OutcomeArguments<TResult, OnFallbackArguments>, ValueTask>? OnFallback { get; set; }
 }
 

src/Polly.Core/Hedging/HedgingStrategyOptions.TResult.cs

@@ -18,45 +18,45 @@ public class HedgingStrategyOptions<TResult> : ResilienceStrategyOptions
     /// Gets or sets the minimal time of waiting before spawning a new hedged call.
     /// </summary>
     /// <remarks>
-    /// Defaults to 2 seconds.
-    /// <para>
     /// You can also use <see cref="TimeSpan.Zero"/> to create all hedged tasks (value of <see cref="MaxHedgedAttempts"/>) at once
     /// or <see cref="System.Threading.Timeout.InfiniteTimeSpan"/> to force the hedging strategy to never create new task before the old one is finished.
-    /// </para>
     /// <para> If you want a greater control over hedging delay customization use <see cref="HedgingDelayGenerator"/>.</para>
     /// </remarks>
+    /// <value>
+    /// The default value is 2 seconds.
+    /// </value>
     public TimeSpan HedgingDelay { get; set; } = HedgingConstants.DefaultHedgingDelay;
 
     /// <summary>
     /// Gets or sets the maximum hedged attempts to perform the desired task.
     /// </summary>
     /// <remarks>
-    /// Defaults to 2. The value must be bigger or equal to 2, and lower or equal to 10.
-    /// <para>
     /// The value defines how many concurrent hedged tasks will be triggered by the strategy.
     /// This includes the primary hedged task that is initially performed, and the further tasks that will
     /// be fetched from the provider and spawned in parallel.
-    /// </para>
     /// </remarks>
+    /// <value>
+    /// The default value is 2. The value must be bigger or equal to 2, and lower or equal to 10.
+    /// </value>
     [Range(HedgingConstants.MinimumHedgedAttempts, HedgingConstants.MaximumHedgedAttempts)]
     public int MaxHedgedAttempts { get; set; } = HedgingConstants.DefaultMaxHedgedAttempts;
 
     /// <summary>
     /// Gets or sets the predicate that determines whether a hedging should be performed for a given result.
     /// </summary>
-    /// <remarks>
-    /// Defaults to a delegate that hedges on any exception except <see cref="OperationCanceledException"/>.
+    /// <value>
+    /// The default value is a predicate that hedges on any exception except <see cref="OperationCanceledException"/>.
     /// This property is required.
-    /// </remarks>
+    /// </value>
     [Required]
     public Func<OutcomeArguments<TResult, HedgingPredicateArguments>, ValueTask<bool>> ShouldHandle { get; set; } = DefaultPredicates<HedgingPredicateArguments, TResult>.HandleOutcome;
 
     /// <summary>
     /// Gets or sets the hedging action generator that creates hedged actions.
     /// </summary>
-    /// <remarks>
-    /// This property is required. The default delegate executes the original callback that was passed to the hedging resilience strategy.
-    /// </remarks>
+    /// <value>
+    /// The default generator executes the original callback that was passed to the hedging resilience strategy. This property is required.
+    /// </value>
     [Required]
     public Func<HedgingActionGeneratorArguments<TResult>, Func<ValueTask<Outcome<TResult>>>?> HedgingActionGenerator { get; set; } = args =>
     {
@@ -76,19 +76,21 @@ public class HedgingStrategyOptions<TResult> : ResilienceStrategyOptions
     /// </summary>
     /// <remarks>
     /// The <see cref="HedgingDelayGenerator"/> takes precedence over <see cref="HedgingDelay"/>. If specified, the <see cref="HedgingDelay"/> is ignored.
-    /// <para>Defaults to <see langword="null"/>.</para>
     /// </remarks>
+    /// <value>
+    /// The default value is <see langword="null"/>.
+    /// </value>
     public Func<HedgingDelayArguments, ValueTask<TimeSpan>>? HedgingDelayGenerator { get; set; }
 
     /// <summary>
     /// Gets or sets the event that is raised when a hedging is performed.
     /// </summary>
     /// <remarks>
-    /// Defaults to <see langword="null"/>.
-    /// <para>
     /// The hedging is executed when the current attempt outcome is not successful and the <see cref="ShouldHandle"/> predicate returns <see langword="true"/> or when
     /// the current attempt did not finish within the <see cref="HedgingDelay"/>.
-    /// </para>
     /// </remarks>
+    /// <value>
+    /// The default value is <see langword="null"/>.
+    /// </value>
     public Func<OutcomeArguments<TResult, OnHedgingArguments>, ValueTask>? OnHedging { get; set; }
 }

src/Polly.Core/PredicateBuilder.TResult.cs

@@ -72,7 +72,7 @@ public PredicateBuilder<TResult> HandleResult(Func<TResult, bool> predicate)
     /// Adds a predicate for handling results with a specific value.
     /// </summary>
     /// <param name="result">The result value to handle.</param>
-    /// <param name="comparer">The comparer to use for comparing results. If null, the default comparer is used.</param>
+    /// <param name="comparer">The comparer to use for comparing results. If <see langword="null"/> , the default comparer is used.</param>
     /// <returns>The same instance of the <see cref="PredicateBuilder{TResult}"/> for chaining.</returns>
     public PredicateBuilder<TResult> HandleResult(TResult result, IEqualityComparer<TResult>? comparer = null)
     {

src/Polly.Core/Registry/ResilienceStrategyRegistryOptions.cs

@@ -11,27 +11,27 @@ public class ResilienceStrategyRegistryOptions<TKey>
     /// <summary>
     /// Gets or sets the factory method that creates instances of <see cref="ResilienceStrategyBuilder"/>.
     /// </summary>
-    /// <remarks>
-    /// By default, the factory method creates a new instance of <see cref="ResilienceStrategyBuilder"/> using the default constructor.
-    /// </remarks>
+    /// <value>
+    /// The default value is a function that creates a new instance of <see cref="ResilienceStrategyBuilder"/> using the default constructor.
+    /// </value>
     [Required]
     public Func<ResilienceStrategyBuilder> BuilderFactory { get; set; } = static () => new ResilienceStrategyBuilder();
 
     /// <summary>
     /// Gets or sets the comparer that is used by the registry to retrieve the resilience strategies.
     /// </summary>
-    /// <remarks>
-    /// By default, the comparer uses the default equality comparer for <typeparamref name="TKey"/>.
-    /// </remarks>
+    /// <value>
+    /// The default value is <see cref="EqualityComparer{T}.Default"/>.
+    /// </value>
     [Required]
     public IEqualityComparer<TKey> StrategyComparer { get; set; } = EqualityComparer<TKey>.Default;
 
     /// <summary>
     /// Gets or sets the comparer that is used by the registry to retrieve the resilience strategy builders.
     /// </summary>
-    /// <remarks>
-    /// By default, the comparer uses the default equality comparer for <typeparamref name="TKey"/>.
-    /// </remarks>
+    /// <value>
+    /// The default value is <see cref="EqualityComparer{T}.Default"/>.
+    /// </value>
     [Required]
     public IEqualityComparer<TKey> BuilderComparer { get; set; } = EqualityComparer<TKey>.Default;
 
@@ -40,25 +40,25 @@ public class ResilienceStrategyRegistryOptions<TKey>
     /// represents the instance name of the builder.
     /// </summary>
     /// <remarks>
-    /// Defaults to <see langword="null"/>.
-    /// <para>
     /// Use custom formatter for composite keys in case you want to have different metric values for a builder and instance key.
     /// In general, strategies can have the same builder name and different instance names.
-    /// </para>
     /// </remarks>
+    /// <value>
+    /// The default value is <see langword="null"/>.
+    /// </value>
     public Func<TKey, string>? InstanceNameFormatter { get; set; }
 
     /// <summary>
     /// Gets or sets the formatter that is used by the registry to format the <typeparamref name="TKey"/> to a string that
     /// represents the builder name.
     /// </summary>
     /// <remarks>
-    /// By default, the formatter uses the <see cref="object.ToString"/> method.
-    /// <para>
     /// Use custom formatter for composite keys in case you want to have different metric values for a builder and strategy key.
     /// In general, strategies can have the same builder name and different strategy keys.
-    /// </para>
     /// </remarks>
+    /// <value>
+    /// The default value is a formatter that formats the keys using the <see cref="object.ToString"/> method.
+    /// </value>
     [Required]
     public Func<TKey, string> BuilderNameFormatter { get; set; } = (key) => key?.ToString() ?? string.Empty;
 }

src/Polly.Core/ResilienceContext.cs

@@ -32,10 +32,8 @@ private ResilienceContext()
     /// Resilience strategy instances are commonly reused across multiple call sites.
     /// Set an <see cref="OperationKey"/> so that logging and metrics can distinguish usages of policy instances at different call sites.
     /// The operation key value should have a low cardinality (i.e. do not assign values such as <see cref="Guid"/> to this property).
-    /// <para>
-    /// Defaults to <see langword="null"/>.
-    /// </para>
     /// </remarks>
+    /// <value>The default value is <see langword="null"/>.</value>
     public string? OperationKey { get; private set; }
 
     /// <summary>