From 613279e8f48c61c43939f71509efcf97b213b10d Mon Sep 17 00:00:00 2001 From: gintsk <3540004+gintsk@users.noreply.github.com> Date: Tue, 5 Mar 2024 22:55:08 +0200 Subject: [PATCH] XML documentation cleanup (#2008) * Enable documentation generation for `Polly` * Fix CS1734 "XML comment on '{1}' has a paramref tag for '{0}', but there is no parameter by that name" * Fix CS1658 "Type parameter declaration must be an identifier not a type." * Fix SA1616 "Element return value documentation should have text" * Fix SA1648 "inheritdoc should be used with inheriting class" * Fix SA1642 "Constructor summary documentation should begin with standard text" * Fix SA1629 "Documentation text should end with a period" * Fix SA1619 "The documentation for type parameter 'TResult' is missing" * Fix CA1200 "Avoid using cref tags with a prefix" * Fix SA1600 "Elements should be documented" --- src/Polly/AsyncPolicy.TResult.cs | 4 +- src/Polly/AsyncPolicy.cs | 4 +- .../Bulkhead/AsyncBulkheadTResultSyntax.cs | 1 - src/Polly/Bulkhead/BulkheadPolicy.cs | 1 - src/Polly/Caching/AsyncCacheSyntax.cs | 4 +- src/Polly/Caching/AsyncCacheTResultSyntax.cs | 10 ++--- .../Caching/AsyncSerializingCacheProvider.cs | 2 +- src/Polly/Caching/CacheProviderExtensions.cs | 4 +- src/Polly/Caching/CacheSyntax.cs | 4 +- src/Polly/Caching/CacheTResultSyntax.cs | 10 ++--- src/Polly/Caching/DefaultCacheKeyStrategy.cs | 4 +- src/Polly/Caching/ICacheItemSerializer.cs | 4 +- src/Polly/Caching/ICacheKeyStrategy.cs | 4 +- src/Polly/Caching/NonSlidingTtl.cs | 2 +- src/Polly/Caching/ResultTtl.cs | 4 +- src/Polly/Caching/SerializingCacheProvider.cs | 2 +- src/Polly/Caching/SlidingTtl.cs | 2 +- src/Polly/Caching/Ttl.cs | 6 +-- src/Polly/Caching/TtlStrategyExtensions.cs | 2 +- .../CircuitBreaker/CircuitBreakerSyntax.cs | 2 - .../CircuitBreakerTResultSyntax.cs | 2 - .../CircuitBreaker/ICircuitController.cs | 43 +++++++++++++++++++ src/Polly/CircuitBreaker/IHealthMetrics.cs | 17 ++++++++ src/Polly/Context.Dictionary.cs | 5 +++ src/Polly/DelegateResult.cs | 4 +- src/Polly/IsPolicy.cs | 2 +- src/Polly/NoOp/NoOpPolicy.cs | 2 +- src/Polly/Policy.TResult.cs | 5 ++- src/Polly/Policy.cs | 4 +- src/Polly/PolicyBase.ContextAndKeys.cs | 10 ++--- src/Polly/PolicyBase.cs | 8 ++-- src/Polly/PolicyBuilder.cs | 9 ++-- src/Polly/Polly.csproj | 1 + .../RateLimit/AsyncRateLimitTResultSyntax.cs | 2 +- src/Polly/RateLimit/IRateLimiter.cs | 2 +- src/Polly/RateLimit/RateLimitTResultSyntax.cs | 2 +- .../Registry/IConcurrentPolicyRegistry.cs | 2 +- src/Polly/Registry/PolicyRegistry.cs | 2 +- src/Polly/Retry/AsyncRetrySyntax.cs | 4 +- src/Polly/Retry/AsyncRetryTResultSyntax.cs | 4 +- src/Polly/Utilities/SystemClock.cs | 2 +- .../Wrap/AsyncPolicyWrap.ContextAndKeys.cs | 8 ++-- src/Polly/Wrap/AsyncPolicyWrap.cs | 8 ++-- src/Polly/Wrap/IPolicyWrap.cs | 4 +- src/Polly/Wrap/PolicyWrap.ContextAndKeys.cs | 8 ++-- src/Polly/Wrap/PolicyWrap.cs | 8 ++-- 46 files changed, 153 insertions(+), 91 deletions(-) diff --git a/src/Polly/AsyncPolicy.TResult.cs b/src/Polly/AsyncPolicy.TResult.cs index 74796e79f08..55704841faf 100644 --- a/src/Polly/AsyncPolicy.TResult.cs +++ b/src/Polly/AsyncPolicy.TResult.cs @@ -8,7 +8,7 @@ namespace Polly; public abstract partial class AsyncPolicy : PolicyBase { /// - /// Constructs a new instance of a derived type with the passed and . + /// Initializes a new instance of the class. /// /// Predicates indicating which exceptions the policy should handle. /// Predicates indicating which results the policy should handle. @@ -20,7 +20,7 @@ internal AsyncPolicy( } /// - /// Constructs a new instance of a derived type with the passed . + /// Initializes a new instance of the class. /// /// A indicating which exceptions and results the policy should handle. protected AsyncPolicy(PolicyBuilder? policyBuilder = null) diff --git a/src/Polly/AsyncPolicy.cs b/src/Polly/AsyncPolicy.cs index 46fbd60f15d..3829723fdf2 100644 --- a/src/Polly/AsyncPolicy.cs +++ b/src/Polly/AsyncPolicy.cs @@ -7,7 +7,7 @@ namespace Polly; public abstract partial class AsyncPolicy { /// - /// Constructs a new instance of a derived type with the passed . + /// Initializes a new instance of the class. /// /// Predicates indicating which exceptions the policy should handle. internal AsyncPolicy(ExceptionPredicates exceptionPredicates) @@ -16,7 +16,7 @@ internal AsyncPolicy(ExceptionPredicates exceptionPredicates) } /// - /// Constructs a new instance of a derived type with the passed . + /// Initializes a new instance of the class. /// /// A specifying which exceptions the policy should handle. protected AsyncPolicy(PolicyBuilder? policyBuilder = null) diff --git a/src/Polly/Bulkhead/AsyncBulkheadTResultSyntax.cs b/src/Polly/Bulkhead/AsyncBulkheadTResultSyntax.cs index 721cb65923d..b31a35104fb 100644 --- a/src/Polly/Bulkhead/AsyncBulkheadTResultSyntax.cs +++ b/src/Polly/Bulkhead/AsyncBulkheadTResultSyntax.cs @@ -36,7 +36,6 @@ public static AsyncBulkheadPolicy BulkheadAsync(int maxParalle /// The policy instance. /// maxParallelization;Value must be greater than zero. /// maxQueuingActions;Value must be greater than or equal to zero. - /// Thrown when is . public static AsyncBulkheadPolicy BulkheadAsync(int maxParallelization, int maxQueuingActions) { Func doNothingAsync = _ => TaskHelper.EmptyTask; diff --git a/src/Polly/Bulkhead/BulkheadPolicy.cs b/src/Polly/Bulkhead/BulkheadPolicy.cs index 4b07cb086b5..35c3dd0963b 100644 --- a/src/Polly/Bulkhead/BulkheadPolicy.cs +++ b/src/Polly/Bulkhead/BulkheadPolicy.cs @@ -58,7 +58,6 @@ public class BulkheadPolicy : Policy, IBulkheadPolicy private readonly int _maxQueueingActions; private readonly Action _onBulkheadRejected; - /// internal BulkheadPolicy( int maxParallelization, int maxQueueingActions, diff --git a/src/Polly/Caching/AsyncCacheSyntax.cs b/src/Polly/Caching/AsyncCacheSyntax.cs index 3467f22d1ef..9fa5db45101 100644 --- a/src/Polly/Caching/AsyncCacheSyntax.cs +++ b/src/Polly/Caching/AsyncCacheSyntax.cs @@ -5,7 +5,7 @@ public partial class Policy { /// /// Builds an that will function like a result cache for delegate executions returning a result. - /// Before executing a delegate returning a result, checks whether the holds a value for the cache key specified by . + /// Before executing a delegate returning a result, checks whether the holds a value for the cache key specified by . /// If the provides a value, returns that value and does not execute the governed delegate. If the does not provide a value, executes the governed delegate, stores the value with the , then returns the value. /// /// @@ -19,7 +19,7 @@ public static AsyncCachePolicy CacheAsync(IAsyncCacheProvider cacheProvider, Tim /// /// Builds an that will function like a result cache for delegate executions returning a result. - /// Before executing a delegate returning a result, checks whether the holds a value for the cache key specified by + /// Before executing a delegate returning a result, checks whether the holds a value for the cache key specified by /// If the provides a value, returns that value and does not execute the governed delegate. If the does not provide a value, executes the governed delegate, stores the value with the , then returns the value. /// /// diff --git a/src/Polly/Caching/AsyncCacheTResultSyntax.cs b/src/Polly/Caching/AsyncCacheTResultSyntax.cs index 1fff0139e7b..91d43c9bbc7 100644 --- a/src/Polly/Caching/AsyncCacheTResultSyntax.cs +++ b/src/Polly/Caching/AsyncCacheTResultSyntax.cs @@ -5,7 +5,7 @@ public partial class Policy { /// /// Builds an that will function like a result cache for delegate executions returning a . - /// Before executing a delegate, checks whether the holds a value for the cache key specified by . + /// Before executing a delegate, checks whether the holds a value for the cache key specified by . /// If the provides a value from cache, returns that value and does not execute the governed delegate. If the does not provide a value, executes the governed delegate, stores the value with the , then returns the value. /// /// @@ -24,7 +24,7 @@ public static AsyncCachePolicy CacheAsync(IAsyncCacheProvider /// /// Builds an that will function like a result cache for delegate executions returning a . - /// Before executing a delegate, checks whether the holds a value for the cache key specified by . + /// Before executing a delegate, checks whether the holds a value for the cache key specified by . /// If the provides a value from cache, returns that value and does not execute the governed delegate. If the does not provide a value, executes the governed delegate, stores the value with the , then returns the value. /// /// @@ -343,7 +343,7 @@ public static AsyncCachePolicy CacheAsync( /// /// Builds an that will function like a result cache for delegate executions returning a . - /// Before executing a delegate, checks whether the holds a value for the cache key specified by . + /// Before executing a delegate, checks whether the holds a value for the cache key specified by . /// If the provides a value from cache, returns that value and does not execute the governed delegate. If the does not provide a value, executes the governed delegate, stores the value with the , then returns the value. /// /// @@ -357,7 +357,7 @@ public static AsyncCachePolicy CacheAsync(IAsyncCacheProvider< /// /// Builds an that will function like a result cache for delegate executions returning a . - /// Before executing a delegate, checks whether the holds a value for the cache key specified by . + /// Before executing a delegate, checks whether the holds a value for the cache key specified by . /// If the provides a value from cache, returns that value and does not execute the governed delegate. If the does not provide a value, executes the governed delegate, stores the value with the , then returns the value. /// /// @@ -372,7 +372,7 @@ public static AsyncCachePolicy CacheAsync(IAsyncCacheProvider< /// /// Builds an that will function like a result cache for delegate executions returning a . - /// Before executing a delegate, checks whether the holds a value for the cache key specified by . + /// Before executing a delegate, checks whether the holds a value for the cache key specified by . /// If the provides a value from cache, returns that value and does not execute the governed delegate. If the does not provide a value, executes the governed delegate, stores the value with the , then returns the value. /// /// diff --git a/src/Polly/Caching/AsyncSerializingCacheProvider.cs b/src/Polly/Caching/AsyncSerializingCacheProvider.cs index 0d0caeaa66d..259c98318f9 100644 --- a/src/Polly/Caching/AsyncSerializingCacheProvider.cs +++ b/src/Polly/Caching/AsyncSerializingCacheProvider.cs @@ -11,7 +11,7 @@ public class AsyncSerializingCacheProvider : IAsyncCacheProvider private readonly ICacheItemSerializer _serializer; /// - /// Initializes a new instance of the class. + /// Initializes a new instance of the class. /// /// The wrapped cache provider. /// The serializer. diff --git a/src/Polly/Caching/CacheProviderExtensions.cs b/src/Polly/Caching/CacheProviderExtensions.cs index c986a1c9f5f..a0459f63620 100644 --- a/src/Polly/Caching/CacheProviderExtensions.cs +++ b/src/Polly/Caching/CacheProviderExtensions.cs @@ -7,7 +7,7 @@ namespace Polly.Caching; public static class CacheProviderExtensions { /// - /// Provides a strongly -typed version of the supplied + /// Provides a strongly -typed version of the supplied . /// /// The type the returned will handle. /// The non-generic cache provider to wrap. @@ -16,7 +16,7 @@ public static ISyncCacheProvider For(this ISyncCache new GenericCacheProvider(nonGenericCacheProvider); /// - /// Provides a strongly -typed version of the supplied + /// Provides a strongly -typed version of the supplied . /// /// The type the returned will handle. /// The non-generic cache provider to wrap. diff --git a/src/Polly/Caching/CacheSyntax.cs b/src/Polly/Caching/CacheSyntax.cs index d0ee51653fa..350dd3b1111 100644 --- a/src/Polly/Caching/CacheSyntax.cs +++ b/src/Polly/Caching/CacheSyntax.cs @@ -5,7 +5,7 @@ public partial class Policy { /// /// Builds a that will function like a result cache for delegate executions returning a result. - /// Before executing a delegate returning a result, checks whether the holds a value for the cache key specified by . + /// Before executing a delegate returning a result, checks whether the holds a value for the cache key specified by . /// If the provides a value from cache, returns that value and does not execute the governed delegate. If the does not provide a value, executes the governed delegate, stores the value with the , then returns the value. /// /// @@ -19,7 +19,7 @@ public static CachePolicy Cache(ISyncCacheProvider cacheProvider, TimeSpan ttl, /// /// Builds a that will function like a result cache for delegate executions returning a result. - /// Before executing a delegate returning a result, checks whether the holds a value for the cache key specified by . + /// Before executing a delegate returning a result, checks whether the holds a value for the cache key specified by . /// If the provides a value from cache, returns that value and does not execute the governed delegate. If the does not provide a value, executes the governed delegate, stores the value with the , then returns the value. /// /// diff --git a/src/Polly/Caching/CacheTResultSyntax.cs b/src/Polly/Caching/CacheTResultSyntax.cs index c0ab9fda3cf..d96ec358335 100644 --- a/src/Polly/Caching/CacheTResultSyntax.cs +++ b/src/Polly/Caching/CacheTResultSyntax.cs @@ -5,7 +5,7 @@ public partial class Policy { /// /// Builds a that will function like a result cache for delegate executions returning a . - /// Before executing a delegate, checks whether the holds a value for the cache key specified by . + /// Before executing a delegate, checks whether the holds a value for the cache key specified by . /// If the provides a value from cache, returns that value and does not execute the governed delegate. If the does not provide a value, executes the governed delegate, stores the value with the , then returns the value. /// /// @@ -24,7 +24,7 @@ public static CachePolicy Cache(ISyncCacheProvider cacheProvid /// /// Builds a that will function like a result cache for delegate executions returning a . - /// Before executing a delegate, checks whether the holds a value for the cache key specified by . + /// Before executing a delegate, checks whether the holds a value for the cache key specified by . /// If the provides a value from cache, returns that value and does not execute the governed delegate. If the does not provide a value, executes the governed delegate, stores the value with the , then returns the value. /// /// @@ -343,7 +343,7 @@ public static CachePolicy Cache( /// /// Builds a that will function like a result cache for delegate executions returning a . - /// Before executing a delegate, checks whether the holds a value for the cache key specified by . + /// Before executing a delegate, checks whether the holds a value for the cache key specified by . /// If the provides a value from cache, returns that value and does not execute the governed delegate. If the does not provide a value, executes the governed delegate, stores the value with the , then returns the value. /// /// @@ -357,7 +357,7 @@ public static CachePolicy Cache(ISyncCacheProvider ca /// /// Builds a that will function like a result cache for delegate executions returning a . - /// Before executing a delegate, checks whether the holds a value for the cache key specified by . + /// Before executing a delegate, checks whether the holds a value for the cache key specified by . /// If the provides a value from cache, returns that value and does not execute the governed delegate. If the does not provide a value, executes the governed delegate, stores the value with the , then returns the value. /// /// @@ -372,7 +372,7 @@ public static CachePolicy Cache(ISyncCacheProvider ca /// /// Builds a that will function like a result cache for delegate executions returning a . - /// Before executing a delegate, checks whether the holds a value for the cache key specified by . + /// Before executing a delegate, checks whether the holds a value for the cache key specified by . /// If the provides a value from cache, returns that value and does not execute the governed delegate. If the does not provide a value, executes the governed delegate, stores the value with the , then returns the value. /// /// diff --git a/src/Polly/Caching/DefaultCacheKeyStrategy.cs b/src/Polly/Caching/DefaultCacheKeyStrategy.cs index 2f8de38c0bd..7ea0eb4a9e5 100644 --- a/src/Polly/Caching/DefaultCacheKeyStrategy.cs +++ b/src/Polly/Caching/DefaultCacheKeyStrategy.cs @@ -2,7 +2,7 @@ namespace Polly.Caching; /// -/// The default cache key strategy for . Returns the property . +/// The default cache key strategy for . Returns the property . /// public class DefaultCacheKeyStrategy : ICacheKeyStrategy { @@ -10,7 +10,7 @@ public class DefaultCacheKeyStrategy : ICacheKeyStrategy /// Gets the cache key from the given execution context. /// /// The execution context. - /// The cache key + /// The cache key. public string GetCacheKey(Context context) => context.OperationKey; diff --git a/src/Polly/Caching/ICacheItemSerializer.cs b/src/Polly/Caching/ICacheItemSerializer.cs index 069f2d96076..d79ad83642d 100644 --- a/src/Polly/Caching/ICacheItemSerializer.cs +++ b/src/Polly/Caching/ICacheItemSerializer.cs @@ -12,13 +12,13 @@ public interface ICacheItemSerializer /// Serializes the specified object. /// /// The object to serialize. - /// The serialized object + /// The serialized object. TSerialized? Serialize(TResult? objectToSerialize); /// /// Deserializes the specified object. /// /// The object to deserialize. - /// The deserialized object + /// The deserialized object. TResult? Deserialize(TSerialized? objectToDeserialize); } diff --git a/src/Polly/Caching/ICacheKeyStrategy.cs b/src/Polly/Caching/ICacheKeyStrategy.cs index bde94cb4364..496c90eb8c6 100644 --- a/src/Polly/Caching/ICacheKeyStrategy.cs +++ b/src/Polly/Caching/ICacheKeyStrategy.cs @@ -2,7 +2,7 @@ namespace Polly.Caching; /// -/// Defines how a should get a string cache key from an execution +/// Defines how a should get a string cache key from an execution . /// public interface ICacheKeyStrategy { @@ -10,6 +10,6 @@ public interface ICacheKeyStrategy /// Gets the cache key from the given execution context. /// /// The execution context. - /// The cache key + /// The cache key. string GetCacheKey(Context context); } diff --git a/src/Polly/Caching/NonSlidingTtl.cs b/src/Polly/Caching/NonSlidingTtl.cs index 6f2e763b0bb..8f4cc09b9c0 100644 --- a/src/Polly/Caching/NonSlidingTtl.cs +++ b/src/Polly/Caching/NonSlidingTtl.cs @@ -12,7 +12,7 @@ public abstract class NonSlidingTtl : ITtlStrategy protected readonly DateTimeOffset absoluteExpirationTime; /// - /// Constructs a new instance of the strategy. + /// Initializes a new instance of the class. /// /// The absolute expiration time for cache items, represented by this strategy. protected NonSlidingTtl(DateTimeOffset absoluteExpirationTime) => diff --git a/src/Polly/Caching/ResultTtl.cs b/src/Polly/Caching/ResultTtl.cs index 957a821f2a9..ae24f731eae 100644 --- a/src/Polly/Caching/ResultTtl.cs +++ b/src/Polly/Caching/ResultTtl.cs @@ -10,7 +10,7 @@ public class ResultTtl : ITtlStrategy private readonly Func _ttlFunc; /// - /// Constructs a new instance of the ttl strategy, with a func calculating based on the value to cache. + /// Initializes a new instance of the class, with a func calculating based on the value to cache. /// /// The function to calculate the TTL for which cache items should be considered valid. public ResultTtl(Func ttlFunc) @@ -21,7 +21,7 @@ public ResultTtl(Func ttlFunc) } /// - /// Constructs a new instance of the ttl strategy, with a func calculating based on the execution and value to cache. + /// Initializes a new instance of the class, with a func calculating based on the execution and value to cache. /// /// The function to calculate the TTL for which cache items should be considered valid. public ResultTtl(Func ttlFunc) => diff --git a/src/Polly/Caching/SerializingCacheProvider.cs b/src/Polly/Caching/SerializingCacheProvider.cs index 19942157a7f..346119b145f 100644 --- a/src/Polly/Caching/SerializingCacheProvider.cs +++ b/src/Polly/Caching/SerializingCacheProvider.cs @@ -11,7 +11,7 @@ public class SerializingCacheProvider : ISyncCacheProvider private readonly ICacheItemSerializer _serializer; /// - /// Initializes a new instance of the class. + /// Initializes a new instance of the class. /// /// The wrapped cache provider. /// The serializer. diff --git a/src/Polly/Caching/SlidingTtl.cs b/src/Polly/Caching/SlidingTtl.cs index 7ef4feb3462..3c446dced49 100644 --- a/src/Polly/Caching/SlidingTtl.cs +++ b/src/Polly/Caching/SlidingTtl.cs @@ -9,7 +9,7 @@ public class SlidingTtl : ITtlStrategy private readonly Ttl ttl; /// - /// Constructs a new instance of the ttl strategy. + /// Initializes a new instance of the class. /// /// The sliding timespan for which cache items should be considered valid. public SlidingTtl(TimeSpan slidingTtl) diff --git a/src/Polly/Caching/Ttl.cs b/src/Polly/Caching/Ttl.cs index 1259620710e..6521e0ad54c 100644 --- a/src/Polly/Caching/Ttl.cs +++ b/src/Polly/Caching/Ttl.cs @@ -17,7 +17,7 @@ public struct Ttl public bool SlidingExpiration; /// - /// Creates a new struct. + /// Initializes a new instance of the struct. /// /// The timespan for which this cache-item remains valid. /// Will be considered as not denoting sliding expiration. @@ -27,9 +27,9 @@ public Ttl(TimeSpan timeSpan) } /// - /// Creates a new struct. + /// Initializes a new instance of the struct. /// - /// The timespan for which this cache-item remains valid + /// The timespan for which this cache-item remains valid. /// Whether this should be considered as sliding expiration. public Ttl(TimeSpan timeSpan, bool slidingExpiration) { diff --git a/src/Polly/Caching/TtlStrategyExtensions.cs b/src/Polly/Caching/TtlStrategyExtensions.cs index 0b9fe7adff5..d3584f1c1cb 100644 --- a/src/Polly/Caching/TtlStrategyExtensions.cs +++ b/src/Polly/Caching/TtlStrategyExtensions.cs @@ -7,7 +7,7 @@ namespace Polly.Caching; internal static class TtlStrategyExtensions { /// - /// Provides a strongly -typed version of the supplied + /// Provides a strongly -typed version of the supplied . /// /// The type the returned will handle. /// The non-generic ttl strategy to wrap. diff --git a/src/Polly/CircuitBreaker/CircuitBreakerSyntax.cs b/src/Polly/CircuitBreaker/CircuitBreakerSyntax.cs index 2b80229d05c..df960a15a1e 100644 --- a/src/Polly/CircuitBreaker/CircuitBreakerSyntax.cs +++ b/src/Polly/CircuitBreaker/CircuitBreakerSyntax.cs @@ -23,8 +23,6 @@ public static class CircuitBreakerSyntax /// The policy instance. /// (see "Release It!" by Michael T. Nygard fi). /// exceptionsAllowedBeforeBreaking;Value must be greater than zero. - /// Thrown when is . - /// Thrown when is . public static CircuitBreakerPolicy CircuitBreaker(this PolicyBuilder policyBuilder, int exceptionsAllowedBeforeBreaking, TimeSpan durationOfBreak) { Action doNothingOnBreak = (_, _) => { }; diff --git a/src/Polly/CircuitBreaker/CircuitBreakerTResultSyntax.cs b/src/Polly/CircuitBreaker/CircuitBreakerTResultSyntax.cs index 5861ae75acb..1f85c40ae67 100644 --- a/src/Polly/CircuitBreaker/CircuitBreakerTResultSyntax.cs +++ b/src/Polly/CircuitBreaker/CircuitBreakerTResultSyntax.cs @@ -23,8 +23,6 @@ public static class CircuitBreakerTResultSyntax /// The policy instance. /// (see "Release It!" by Michael T. Nygard fi). /// handledEventsAllowedBeforeBreaking;Value must be greater than zero. - /// Thrown when is . - /// Thrown when is . public static CircuitBreakerPolicy CircuitBreaker(this PolicyBuilder policyBuilder, int handledEventsAllowedBeforeBreaking, TimeSpan durationOfBreak) { Action, TimeSpan> doNothingOnBreak = (_, _) => { }; diff --git a/src/Polly/CircuitBreaker/ICircuitController.cs b/src/Polly/CircuitBreaker/ICircuitController.cs index a6f28a65507..e17ffc47e78 100644 --- a/src/Polly/CircuitBreaker/ICircuitController.cs +++ b/src/Polly/CircuitBreaker/ICircuitController.cs @@ -1,14 +1,57 @@ namespace Polly.CircuitBreaker; +/// +/// Interface for controlling a circuit breaker. +/// +/// The type of the result. internal interface ICircuitController { + /// + /// Gets the state of the circuit. + /// CircuitState CircuitState { get; } + + /// + /// Gets the last exception that was handled by the circuit breaker. + /// Exception LastException { get; } + + /// + /// Gets the last result that was handled by the circuit breaker. + /// TResult LastHandledResult { get; } + + /// + /// Isolates the circuit breaker. + /// void Isolate(); + + /// + /// Resets the circuit breaker. + /// void Reset(); + + /// + /// Handles the circuit reset event. + /// + /// The context. void OnCircuitReset(Context context); + + /// + /// Handles the action pre-execute event. + /// void OnActionPreExecute(); + + /// + /// Handles the action success event. + /// + /// The context. void OnActionSuccess(Context context); + + /// + /// Handles the action failure event. + /// + /// The outcome of the delegate. + /// The context. void OnActionFailure(DelegateResult outcome, Context context); } diff --git a/src/Polly/CircuitBreaker/IHealthMetrics.cs b/src/Polly/CircuitBreaker/IHealthMetrics.cs index 0df590f49ee..12c9d055fd7 100644 --- a/src/Polly/CircuitBreaker/IHealthMetrics.cs +++ b/src/Polly/CircuitBreaker/IHealthMetrics.cs @@ -1,11 +1,28 @@ namespace Polly.CircuitBreaker; +/// +/// Interface for managing health metrics. +/// internal interface IHealthMetrics { + /// + /// Increments the success count. + /// void IncrementSuccess_NeedsLock(); + + /// + /// Increments the failure count. + /// void IncrementFailure_NeedsLock(); + /// + /// Resets the health metrics. + /// void Reset_NeedsLock(); + /// + /// Gets the health count. + /// + /// The current health count. HealthCount GetHealthCount_NeedsLock(); } diff --git a/src/Polly/Context.Dictionary.cs b/src/Polly/Context.Dictionary.cs index ece544b1e72..ff2c091d960 100644 --- a/src/Polly/Context.Dictionary.cs +++ b/src/Polly/Context.Dictionary.cs @@ -118,8 +118,11 @@ public void CopyTo(Array array, int index) => #endregion #region IReadOnlyDictionary implementation + + /// IEnumerable IReadOnlyDictionary.Keys => ((IReadOnlyDictionary)WrappedDictionary).Keys; + /// IEnumerable IReadOnlyDictionary.Values => ((IReadOnlyDictionary)WrappedDictionary).Values; #endregion @@ -132,8 +135,10 @@ public void CopyTo(Array array, int index) => /// bool IDictionary.IsReadOnly => ((IDictionary)WrappedDictionary).IsReadOnly; + /// ICollection IDictionary.Keys => ((IDictionary)WrappedDictionary).Keys; + /// ICollection IDictionary.Values => ((IDictionary)WrappedDictionary).Values; /// diff --git a/src/Polly/DelegateResult.cs b/src/Polly/DelegateResult.cs index 03ed21f7cac..fc2bc3fc04c 100644 --- a/src/Polly/DelegateResult.cs +++ b/src/Polly/DelegateResult.cs @@ -6,13 +6,13 @@ public class DelegateResult { /// - /// Create an instance of representing an execution which returned . + /// Initializes a new instance of the class representing an execution which returned . /// /// The result. public DelegateResult(TResult result) => Result = result; /// - /// Create an instance of representing an execution which threw . + /// Initializes a new instance of the class representing an execution which threw . /// /// The exception. public DelegateResult(Exception exception) => diff --git a/src/Polly/IsPolicy.cs b/src/Polly/IsPolicy.cs index 8ce835ab065..6a03837b5bd 100644 --- a/src/Polly/IsPolicy.cs +++ b/src/Polly/IsPolicy.cs @@ -6,7 +6,7 @@ public interface IsPolicy { /// - /// A key intended to be unique to each policy instance, which is passed with executions as the property. + /// A key intended to be unique to each policy instance, which is passed with executions as the property. /// string PolicyKey { get; } } diff --git a/src/Polly/NoOp/NoOpPolicy.cs b/src/Polly/NoOp/NoOpPolicy.cs index 1c8add979e8..cc4f0a02b13 100644 --- a/src/Polly/NoOp/NoOpPolicy.cs +++ b/src/Polly/NoOp/NoOpPolicy.cs @@ -18,7 +18,7 @@ protected override TResult Implementation(Func -/// A no op policy that can be applied to delegates returning a value of type +/// A no op policy that can be applied to delegates returning a value of type . /// /// The type of return values this policy will handle. public class NoOpPolicy : Policy, INoOpPolicy diff --git a/src/Polly/Policy.TResult.cs b/src/Polly/Policy.TResult.cs index c9c54b48bd1..5337c86e90c 100644 --- a/src/Polly/Policy.TResult.cs +++ b/src/Polly/Policy.TResult.cs @@ -4,10 +4,11 @@ namespace Polly; /// /// Transient fault handling policies that can be applied to delegates returning results of type . /// +/// The type of return value of the delegate that the policy will be applied to. public abstract partial class Policy : PolicyBase { /// - /// Constructs a new instance of a derived type with the passed and . + /// Initializes a new instance of the class. /// /// Predicates indicating which exceptions the policy should handle. /// Predicates indicating which results the policy should handle. @@ -17,7 +18,7 @@ internal Policy(ExceptionPredicates exceptionPredicates, ResultPredicates - /// Constructs a new instance of a derived type with the passed . + /// Initializes a new instance of the class. /// /// A indicating which exceptions and results the policy should handle. protected Policy(PolicyBuilder? policyBuilder = null) diff --git a/src/Polly/Policy.cs b/src/Polly/Policy.cs index 7d3b85fce51..6fa155e6616 100644 --- a/src/Polly/Policy.cs +++ b/src/Polly/Policy.cs @@ -7,7 +7,7 @@ namespace Polly; public abstract partial class Policy : PolicyBase { /// - /// Constructs a new instance of a derived type with the passed . + /// Initializes a new instance of the class. /// /// Predicates indicating which exceptions the policy should handle. internal Policy(ExceptionPredicates exceptionPredicates) @@ -16,7 +16,7 @@ internal Policy(ExceptionPredicates exceptionPredicates) } /// - /// Constructs a new instance of a derived type with the passed . + /// Initializes a new instance of the class. /// /// A specifying which exceptions the policy should handle. protected Policy(PolicyBuilder? policyBuilder = null) diff --git a/src/Polly/PolicyBase.ContextAndKeys.cs b/src/Polly/PolicyBase.ContextAndKeys.cs index 05e866655cb..e9127f8a8c0 100644 --- a/src/Polly/PolicyBase.ContextAndKeys.cs +++ b/src/Polly/PolicyBase.ContextAndKeys.cs @@ -8,7 +8,7 @@ public abstract partial class PolicyBase protected string policyKeyInternal; /// - /// A key intended to be unique to each instance, which is passed with executions as the property. + /// A key intended to be unique to each instance, which is passed with executions as the property. /// public string PolicyKey => policyKeyInternal ?? (policyKeyInternal = GetType().Name + "-" + KeyHelper.GuidPart()); @@ -18,8 +18,8 @@ public abstract partial class PolicyBase /// Restores the supplied keys to the execution . /// /// The execution . - /// The prior to execution through this policy. - /// The prior to execution through this policy. + /// The prior to execution through this policy. + /// The prior to execution through this policy. internal static void RestorePolicyContext(Context executionContext, string priorPolicyWrapKey, string priorPolicyKey) { executionContext.PolicyWrapKey = priorPolicyWrapKey; @@ -30,8 +30,8 @@ internal static void RestorePolicyContext(Context executionContext, string prior /// Updates the execution with context from the executing policy. /// /// The execution . - /// The prior to changes by this method. - /// The prior to changes by this method. + /// The prior to changes by this method. + /// The prior to changes by this method. internal virtual void SetPolicyContext(Context executionContext, out string priorPolicyWrapKey, out string priorPolicyKey) // priorPolicyWrapKey and priorPolicyKey could be handled as a (string, string) System.ValueTuple return type instead of out parameters, when our minimum supported target supports this. { priorPolicyWrapKey = executionContext.PolicyWrapKey; diff --git a/src/Polly/PolicyBase.cs b/src/Polly/PolicyBase.cs index 7ad06e02981..85f11886fde 100644 --- a/src/Polly/PolicyBase.cs +++ b/src/Polly/PolicyBase.cs @@ -30,14 +30,14 @@ internal static ExceptionType GetExceptionType(ExceptionPredicates exceptionPred } /// - /// Constructs a new instance of a derived type of with the passed . + /// Initializes a new instance of the class. /// /// Predicates indicating which exceptions the policy should handle. internal PolicyBase(ExceptionPredicates exceptionPredicates) => ExceptionPredicates = exceptionPredicates ?? ExceptionPredicates.None; /// - /// Constructs a new instance of a derived type of with the passed . + /// Initializes a new instance of the class. /// /// A indicating which exceptions the policy should handle. protected PolicyBase(PolicyBuilder policyBuilder) @@ -57,7 +57,7 @@ public abstract class PolicyBase : PolicyBase protected internal ResultPredicates ResultPredicates { get; } /// - /// Constructs a new instance of a derived type of . + /// Initializes a new instance of the class. /// /// Predicates indicating which exceptions the policy should handle. /// Predicates indicating which results the policy should handle. @@ -68,7 +68,7 @@ internal PolicyBase( ResultPredicates = resultPredicates ?? ResultPredicates.None; /// - /// Constructs a new instance of a derived type of with the passed . + /// Initializes a new instance of the class. /// /// A indicating which exceptions the policy should handle. protected PolicyBase(PolicyBuilder policyBuilder) diff --git a/src/Polly/PolicyBuilder.cs b/src/Polly/PolicyBuilder.cs index 875da928104..0169dea8e3c 100644 --- a/src/Polly/PolicyBuilder.cs +++ b/src/Polly/PolicyBuilder.cs @@ -52,10 +52,10 @@ public override int GetHashCode() => base.GetHashCode(); /// - /// Gets the of the current instance. + /// Gets the of the current instance. /// /// - /// The instance that represents the exact runtime type of the current instance. + /// The instance that represents the exact runtime type of the current instance. /// [EditorBrowsable(EditorBrowsableState.Never)] public new Type GetType() => @@ -67,6 +67,7 @@ public override int GetHashCode() => /// /// Builder class that holds the list of current execution predicates filtering TResult result values. /// +/// The type of the result value that the execution predicates are filtering. public sealed partial class PolicyBuilder { private PolicyBuilder() @@ -129,10 +130,10 @@ public override int GetHashCode() => base.GetHashCode(); /// - /// Gets the of the current instance. + /// Gets the of the current instance. /// /// - /// The instance that represents the exact runtime type of the current instance. + /// The instance that represents the exact runtime type of the current instance. /// [EditorBrowsable(EditorBrowsableState.Never)] public new Type GetType() => diff --git a/src/Polly/Polly.csproj b/src/Polly/Polly.csproj index e0c5dccb09f..b22ac9d790b 100644 --- a/src/Polly/Polly.csproj +++ b/src/Polly/Polly.csproj @@ -3,6 +3,7 @@ net6.0;netstandard2.0;net472;net462 Polly + true Library 70 true diff --git a/src/Polly/RateLimit/AsyncRateLimitTResultSyntax.cs b/src/Polly/RateLimit/AsyncRateLimitTResultSyntax.cs index 284d2d9fa07..b1f92e9aafe 100644 --- a/src/Polly/RateLimit/AsyncRateLimitTResultSyntax.cs +++ b/src/Polly/RateLimit/AsyncRateLimitTResultSyntax.cs @@ -48,7 +48,7 @@ public static AsyncRateLimitPolicy RateLimitAsync( /// /// Builds a RateLimit that will rate-limit executions to per the timespan given, - /// with a maximum burst size of + /// with a maximum burst size of . /// /// The type of return values this policy will handle. /// The number of executions (call it N) permitted per timespan. diff --git a/src/Polly/RateLimit/IRateLimiter.cs b/src/Polly/RateLimit/IRateLimiter.cs index a6c702e68f9..edbeef66de7 100644 --- a/src/Polly/RateLimit/IRateLimiter.cs +++ b/src/Polly/RateLimit/IRateLimiter.cs @@ -3,7 +3,7 @@ namespace Polly.RateLimit; /// -/// Defines methods to be provided by a rate-limiter used in a Polly +/// Defines methods to be provided by a rate-limiter used in a Polly . /// internal interface IRateLimiter { diff --git a/src/Polly/RateLimit/RateLimitTResultSyntax.cs b/src/Polly/RateLimit/RateLimitTResultSyntax.cs index dd7312ca036..67fc8fb5d0e 100644 --- a/src/Polly/RateLimit/RateLimitTResultSyntax.cs +++ b/src/Polly/RateLimit/RateLimitTResultSyntax.cs @@ -48,7 +48,7 @@ public static RateLimitPolicy RateLimit( /// /// Builds a RateLimit that will rate-limit executions to per the timespan given, - /// with a maximum burst size of + /// with a maximum burst size of . /// /// The type of return values this policy will handle. /// The number of executions (call it N) permitted per timespan. diff --git a/src/Polly/Registry/IConcurrentPolicyRegistry.cs b/src/Polly/Registry/IConcurrentPolicyRegistry.cs index c201e83f066..7c2427ddfe1 100644 --- a/src/Polly/Registry/IConcurrentPolicyRegistry.cs +++ b/src/Polly/Registry/IConcurrentPolicyRegistry.cs @@ -37,7 +37,7 @@ bool TryRemove(TKey key, out TPolicy policy) /// The key whose value is compared with comparisonPolicy, and possibly replaced. /// The policy that replaces the value for the specified , if the comparison results in equality. /// The policy that is compared to the existing policy at the specified key. - /// + /// True if the policy is successfully updated. Otherwise false. bool TryUpdate(TKey key, TPolicy newPolicy, TPolicy comparisonPolicy) where TPolicy : IsPolicy; diff --git a/src/Polly/Registry/PolicyRegistry.cs b/src/Polly/Registry/PolicyRegistry.cs index 022f2025c8a..6e927b3336d 100644 --- a/src/Polly/Registry/PolicyRegistry.cs +++ b/src/Polly/Registry/PolicyRegistry.cs @@ -21,7 +21,7 @@ public PolicyRegistry() } /// - /// Initializes a new instance of the class, with dictionary. + /// Initializes a new instance of the class. /// This internal constructor exists solely to facilitate testing of the GetEnumerator() methods, which allow us to support collection initialisation syntax. /// /// a dictionary containing keys and policies used for testing. diff --git a/src/Polly/Retry/AsyncRetrySyntax.cs b/src/Polly/Retry/AsyncRetrySyntax.cs index 9f0b36dfc8d..ef247265b90 100644 --- a/src/Polly/Retry/AsyncRetrySyntax.cs +++ b/src/Polly/Retry/AsyncRetrySyntax.cs @@ -47,7 +47,7 @@ public static AsyncRetryPolicy RetryAsync(this PolicyBuilder policyBuilder, Acti /// The policy builder. /// The action to call asynchronously on each retry. /// The policy instance. - /// Thrown when is . + /// Thrown when is . public static AsyncRetryPolicy RetryAsync(this PolicyBuilder policyBuilder, Func onRetryAsync) => policyBuilder.RetryAsync(1, onRetryAsync: (outcome, i, _) => onRetryAsync(outcome, i)); @@ -107,7 +107,7 @@ public static AsyncRetryPolicy RetryAsync(this PolicyBuilder policyBuilder, Acti /// The policy builder. /// The action to call asynchronously on each retry. /// The policy instance. - /// Thrown when is . + /// Thrown when is . public static AsyncRetryPolicy RetryAsync(this PolicyBuilder policyBuilder, Func onRetryAsync) => policyBuilder.RetryAsync(1, onRetryAsync); diff --git a/src/Polly/Retry/AsyncRetryTResultSyntax.cs b/src/Polly/Retry/AsyncRetryTResultSyntax.cs index ebb08b1cddc..8770a1420ea 100644 --- a/src/Polly/Retry/AsyncRetryTResultSyntax.cs +++ b/src/Polly/Retry/AsyncRetryTResultSyntax.cs @@ -46,7 +46,7 @@ public static AsyncRetryPolicy RetryAsync(this PolicyBuilderThe policy builder. /// The action to call asynchronously on each retry. /// The policy instance. - /// Thrown when is . + /// Thrown when is . public static AsyncRetryPolicy RetryAsync(this PolicyBuilder policyBuilder, Func, int, Task> onRetryAsync) => policyBuilder.RetryAsync(1, onRetryAsync: (outcome, i, _) => onRetryAsync(outcome, i)); @@ -107,7 +107,7 @@ public static AsyncRetryPolicy RetryAsync(this PolicyBuilderThe policy builder. /// The action to call asynchronously on each retry. /// The policy instance. - /// Thrown when is . + /// Thrown when is . public static AsyncRetryPolicy RetryAsync(this PolicyBuilder policyBuilder, Func, int, Context, Task> onRetryAsync) => policyBuilder.RetryAsync(1, onRetryAsync); diff --git a/src/Polly/Utilities/SystemClock.cs b/src/Polly/Utilities/SystemClock.cs index 7902f61d57d..11a6c871436 100644 --- a/src/Polly/Utilities/SystemClock.cs +++ b/src/Polly/Utilities/SystemClock.cs @@ -18,7 +18,7 @@ public static class SystemClock /// /// Allows the setting of a custom async Sleep implementation for testing. - /// By default this will be a call to taking a . + /// By default this will be a call to taking a . /// public static Func SleepAsync = Task.Delay; diff --git a/src/Polly/Wrap/AsyncPolicyWrap.ContextAndKeys.cs b/src/Polly/Wrap/AsyncPolicyWrap.ContextAndKeys.cs index c9d9f8a92f5..e8f62be9027 100644 --- a/src/Polly/Wrap/AsyncPolicyWrap.ContextAndKeys.cs +++ b/src/Polly/Wrap/AsyncPolicyWrap.ContextAndKeys.cs @@ -6,8 +6,8 @@ public partial class AsyncPolicyWrap /// Updates the execution with context from the executing . /// /// The execution . - /// The prior to changes by this method. - /// The prior to changes by this method. + /// The prior to changes by this method. + /// The prior to changes by this method. internal override void SetPolicyContext(Context executionContext, out string priorPolicyWrapKey, out string priorPolicyKey) { priorPolicyWrapKey = executionContext.PolicyWrapKey; @@ -26,8 +26,8 @@ public partial class AsyncPolicyWrap /// Updates the execution with context from the executing . /// /// The execution . - /// The prior to changes by this method. - /// The prior to changes by this method. + /// The prior to changes by this method. + /// The prior to changes by this method. internal override void SetPolicyContext(Context executionContext, out string priorPolicyWrapKey, out string priorPolicyKey) { priorPolicyWrapKey = executionContext.PolicyWrapKey; diff --git a/src/Polly/Wrap/AsyncPolicyWrap.cs b/src/Polly/Wrap/AsyncPolicyWrap.cs index e1cb77f7f54..c37148196c7 100644 --- a/src/Polly/Wrap/AsyncPolicyWrap.cs +++ b/src/Polly/Wrap/AsyncPolicyWrap.cs @@ -9,12 +9,12 @@ public partial class AsyncPolicyWrap : AsyncPolicy, IPolicyWrap private readonly IAsyncPolicy _inner; /// - /// Returns the outer in this + /// Returns the outer in this . /// public IsPolicy Outer => _outer; /// - /// Returns the next inner in this + /// Returns the next inner in this . /// public IsPolicy Inner => _inner; @@ -66,12 +66,12 @@ public partial class AsyncPolicyWrap : AsyncPolicy, IPolicyWra private readonly IAsyncPolicy _innerGeneric; /// - /// Returns the outer in this + /// Returns the outer in this . /// public IsPolicy Outer => (IsPolicy)_outerGeneric ?? _outerNonGeneric; /// - /// Returns the next inner in this + /// Returns the next inner in this . /// public IsPolicy Inner => (IsPolicy)_innerGeneric ?? _innerNonGeneric; diff --git a/src/Polly/Wrap/IPolicyWrap.cs b/src/Polly/Wrap/IPolicyWrap.cs index 2d1e8f4253d..abea62a2ecd 100644 --- a/src/Polly/Wrap/IPolicyWrap.cs +++ b/src/Polly/Wrap/IPolicyWrap.cs @@ -6,12 +6,12 @@ public interface IPolicyWrap : IsPolicy { /// - /// Returns the outer in this + /// Returns the outer in this . /// IsPolicy Outer { get; } /// - /// Returns the next inner in this + /// Returns the next inner in this . /// IsPolicy Inner { get; } } diff --git a/src/Polly/Wrap/PolicyWrap.ContextAndKeys.cs b/src/Polly/Wrap/PolicyWrap.ContextAndKeys.cs index 90b9468346f..5e02d456d30 100644 --- a/src/Polly/Wrap/PolicyWrap.ContextAndKeys.cs +++ b/src/Polly/Wrap/PolicyWrap.ContextAndKeys.cs @@ -6,8 +6,8 @@ public partial class PolicyWrap /// Updates the execution with context from the executing . /// /// The execution . - /// The prior to changes by this method. - /// The prior to changes by this method. + /// The prior to changes by this method. + /// The prior to changes by this method. internal override void SetPolicyContext(Context executionContext, out string priorPolicyWrapKey, out string priorPolicyKey) { priorPolicyWrapKey = executionContext.PolicyWrapKey; @@ -26,8 +26,8 @@ public partial class PolicyWrap /// Updates the execution with context from the executing . /// /// The execution . - /// The prior to changes by this method. - /// The prior to changes by this method. + /// The prior to changes by this method. + /// The prior to changes by this method. internal override void SetPolicyContext(Context executionContext, out string priorPolicyWrapKey, out string priorPolicyKey) { priorPolicyWrapKey = executionContext.PolicyWrapKey; diff --git a/src/Polly/Wrap/PolicyWrap.cs b/src/Polly/Wrap/PolicyWrap.cs index bce43769c03..27aebef6127 100644 --- a/src/Polly/Wrap/PolicyWrap.cs +++ b/src/Polly/Wrap/PolicyWrap.cs @@ -9,12 +9,12 @@ public partial class PolicyWrap : Policy, IPolicyWrap private readonly ISyncPolicy _inner; /// - /// Returns the outer in this + /// Returns the outer in this . /// public IsPolicy Outer => _outer; /// - /// Returns the next inner in this + /// Returns the next inner in this . /// public IsPolicy Inner => _inner; @@ -59,12 +59,12 @@ public partial class PolicyWrap : Policy, IPolicyWrap private readonly ISyncPolicy _innerGeneric; /// - /// Returns the outer in this + /// Returns the outer in this . /// public IsPolicy Outer => (IsPolicy)_outerGeneric ?? _outerNonGeneric; /// - /// Returns the next inner in this + /// Returns the next inner in this . /// public IsPolicy Inner => (IsPolicy)_innerGeneric ?? _innerNonGeneric;