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

@@ -8,7 +8,7 @@ namespace Polly;
 public abstract partial class AsyncPolicy<TResult> : PolicyBase<TResult>
 {
     /// <summary>
-    /// Constructs a new instance of a derived <see cref="AsyncPolicy{TResult}"/> type with the passed <paramref name="exceptionPredicates"/> and <paramref name="resultPredicates"/>.
+    /// Initializes a new instance of the <see cref="AsyncPolicy{TResult}"/> class.
     /// </summary>
     /// <param name="exceptionPredicates">Predicates indicating which exceptions the policy should handle. </param>
     /// <param name="resultPredicates">Predicates indicating which results the policy should handle. </param>
@@ -20,7 +20,7 @@ internal AsyncPolicy(
     }
 
     /// <summary>
-    /// Constructs a new instance of a derived <see cref="AsyncPolicy{TResult}"/> type with the passed <paramref name="policyBuilder"/>.
+    /// Initializes a new instance of the <see cref="AsyncPolicy{TResult}"/> class.
     /// </summary>
     /// <param name="policyBuilder">A <see cref="PolicyBuilder{TResult}"/> indicating which exceptions and results the policy should handle.</param>
     protected AsyncPolicy(PolicyBuilder<TResult>? policyBuilder = null)

src/Polly/AsyncPolicy.cs

@@ -7,7 +7,7 @@ namespace Polly;
 public abstract partial class AsyncPolicy
 {
     /// <summary>
-    /// Constructs a new instance of a derived <see cref="AsyncPolicy"/> type with the passed <paramref name="exceptionPredicates"/>.
+    /// Initializes a new instance of the <see cref="AsyncPolicy"/> class.
     /// </summary>
     /// <param name="exceptionPredicates">Predicates indicating which exceptions the policy should handle. </param>
     internal AsyncPolicy(ExceptionPredicates exceptionPredicates)
@@ -16,7 +16,7 @@ internal AsyncPolicy(ExceptionPredicates exceptionPredicates)
     }
 
     /// <summary>
-    /// Constructs a new instance of a derived <see cref="AsyncPolicy"/> type with the passed <paramref name="policyBuilder"/>.
+    /// Initializes a new instance of the <see cref="AsyncPolicy"/> class.
     /// </summary>
     /// <param name="policyBuilder">A <see cref="PolicyBuilder"/> specifying which exceptions the policy should handle. </param>
     protected AsyncPolicy(PolicyBuilder? policyBuilder = null)

src/Polly/Bulkhead/AsyncBulkheadTResultSyntax.cs

@@ -36,7 +36,6 @@ public static AsyncBulkheadPolicy<TResult> BulkheadAsync<TResult>(int maxParalle
     /// <returns>The policy instance.</returns>
     /// <exception cref="ArgumentOutOfRangeException">maxParallelization;Value must be greater than zero.</exception>
     /// <exception cref="ArgumentOutOfRangeException">maxQueuingActions;Value must be greater than or equal to zero.</exception>
-    /// <exception cref="ArgumentNullException">Thrown when <paramref name="onBulkheadRejectedAsync"/> is <see langword="null"/>.</exception>
     public static AsyncBulkheadPolicy<TResult> BulkheadAsync<TResult>(int maxParallelization, int maxQueuingActions)
     {
         Func<Context, Task> doNothingAsync = _ => TaskHelper.EmptyTask;

src/Polly/Bulkhead/BulkheadPolicy.cs

@@ -58,7 +58,6 @@ public class BulkheadPolicy<TResult> : Policy<TResult>, IBulkheadPolicy<TResult>
     private readonly int _maxQueueingActions;
     private readonly Action<Context> _onBulkheadRejected;
 
-    /// <inheritdoc/>
     internal BulkheadPolicy(
         int maxParallelization,
         int maxQueueingActions,

src/Polly/Caching/AsyncCacheSyntax.cs

@@ -5,7 +5,7 @@ public partial class Policy
 {
     /// <summary>
     /// <para>Builds an <see cref="AsyncPolicy"/> that will function like a result cache for delegate executions returning a result.</para>
-    /// <para>Before executing a delegate returning a result, checks whether the <paramref name="cacheProvider"/> holds a value for the cache key specified by <see cref="M:Context.OperationKey"/>.
+    /// <para>Before executing a delegate returning a result, checks whether the <paramref name="cacheProvider"/> holds a value for the cache key specified by <see cref="Context.OperationKey"/>.
     /// If the <paramref name="cacheProvider"/> provides a value, returns that value and does not execute the governed delegate.  If the <paramref name="cacheProvider"/> does not provide a value, executes the governed delegate, stores the value with the <paramref name="cacheProvider"/>, then returns the value.
     /// </para>
     /// </summary>
@@ -19,7 +19,7 @@ public static AsyncCachePolicy CacheAsync(IAsyncCacheProvider cacheProvider, Tim
 
     /// <summary>
     /// <para>Builds an <see cref="AsyncPolicy"/> that will function like a result cache for delegate executions returning a result.</para>
-    /// <para>Before executing a delegate returning a result, checks whether the <paramref name="cacheProvider"/> holds a value for the cache key specified by <see cref="M:Context.OperationKey"/>
+    /// <para>Before executing a delegate returning a result, checks whether the <paramref name="cacheProvider"/> holds a value for the cache key specified by <see cref="Context.OperationKey"/>
     /// If the <paramref name="cacheProvider"/> provides a value, returns that value and does not execute the governed delegate.  If the <paramref name="cacheProvider"/> does not provide a value, executes the governed delegate, stores the value with the <paramref name="cacheProvider"/>, then returns the value.
     /// </para>
     /// </summary>

src/Polly/Caching/AsyncCacheTResultSyntax.cs

@@ -5,7 +5,7 @@ public partial class Policy
 {
     /// <summary>
     /// <para>Builds an <see cref="AsyncPolicy{TResult}"/> that will function like a result cache for delegate executions returning a <typeparamref name="TResult"/>.</para>
-    /// <para>Before executing a delegate, checks whether the <paramref name="cacheProvider"/> holds a value for the cache key specified by <see cref="M:Context.OperationKey"/>.
+    /// <para>Before executing a delegate, checks whether the <paramref name="cacheProvider"/> holds a value for the cache key specified by <see cref="Context.OperationKey"/>.
     /// If the <paramref name="cacheProvider"/> provides a value from cache, returns that value and does not execute the governed delegate.  If the <paramref name="cacheProvider"/> does not provide a value, executes the governed delegate, stores the value with the <paramref name="cacheProvider"/>, then returns the value.
     /// </para>
     /// </summary>
@@ -24,7 +24,7 @@ public static AsyncCachePolicy<TResult> CacheAsync<TResult>(IAsyncCacheProvider
 
     /// <summary>
     /// <para>Builds an <see cref="AsyncPolicy{TResult}"/> that will function like a result cache for delegate executions returning a <typeparamref name="TResult"/>.</para>
-    /// <para>Before executing a delegate, checks whether the <paramref name="cacheProvider"/> holds a value for the cache key specified by <see cref="M:Context.OperationKey"/>.
+    /// <para>Before executing a delegate, checks whether the <paramref name="cacheProvider"/> holds a value for the cache key specified by <see cref="Context.OperationKey"/>.
     /// If the <paramref name="cacheProvider"/> provides a value from cache, returns that value and does not execute the governed delegate.  If the <paramref name="cacheProvider"/> does not provide a value, executes the governed delegate, stores the value with the <paramref name="cacheProvider"/>, then returns the value.
     /// </para>
     /// </summary>
@@ -343,7 +343,7 @@ public static AsyncCachePolicy<TResult> CacheAsync<TResult>(
 
     /// <summary>
     /// <para>Builds an <see cref="AsyncPolicy{TResult}"/> that will function like a result cache for delegate executions returning a <typeparamref name="TResult"/>.</para>
-    /// <para>Before executing a delegate, checks whether the <paramref name="cacheProvider"/> holds a value for the cache key specified by <see cref="M:Context.OperationKey"/>.
+    /// <para>Before executing a delegate, checks whether the <paramref name="cacheProvider"/> holds a value for the cache key specified by <see cref="Context.OperationKey"/>.
     /// If the <paramref name="cacheProvider"/> provides a value from cache, returns that value and does not execute the governed delegate.  If the <paramref name="cacheProvider"/> does not provide a value, executes the governed delegate, stores the value with the <paramref name="cacheProvider"/>, then returns the value.
     /// </para>
     /// </summary>
@@ -357,7 +357,7 @@ public static AsyncCachePolicy<TResult> CacheAsync<TResult>(IAsyncCacheProvider<
 
     /// <summary>
     /// <para>Builds an <see cref="AsyncPolicy{TResult}"/> that will function like a result cache for delegate executions returning a <typeparamref name="TResult"/>.</para>
-    /// <para>Before executing a delegate, checks whether the <paramref name="cacheProvider"/> holds a value for the cache key specified by <see cref="M:Context.OperationKey"/>.
+    /// <para>Before executing a delegate, checks whether the <paramref name="cacheProvider"/> holds a value for the cache key specified by <see cref="Context.OperationKey"/>.
     /// If the <paramref name="cacheProvider"/> provides a value from cache, returns that value and does not execute the governed delegate.  If the <paramref name="cacheProvider"/> does not provide a value, executes the governed delegate, stores the value with the <paramref name="cacheProvider"/>, then returns the value.
     /// </para>
     /// </summary>
@@ -372,7 +372,7 @@ public static AsyncCachePolicy<TResult> CacheAsync<TResult>(IAsyncCacheProvider<
 
     /// <summary>
     /// <para>Builds an <see cref="AsyncPolicy{TResult}"/> that will function like a result cache for delegate executions returning a <typeparamref name="TResult"/>.</para>
-    /// <para>Before executing a delegate, checks whether the <paramref name="cacheProvider"/> holds a value for the cache key specified by <see cref="M:Context.OperationKey"/>.
+    /// <para>Before executing a delegate, checks whether the <paramref name="cacheProvider"/> holds a value for the cache key specified by <see cref="Context.OperationKey"/>.
     /// If the <paramref name="cacheProvider"/> provides a value from cache, returns that value and does not execute the governed delegate.  If the <paramref name="cacheProvider"/> does not provide a value, executes the governed delegate, stores the value with the <paramref name="cacheProvider"/>, then returns the value.
     /// </para>
     /// </summary>

src/Polly/Caching/AsyncSerializingCacheProvider.cs

@@ -11,7 +11,7 @@ public class AsyncSerializingCacheProvider<TSerialized> : IAsyncCacheProvider
     private readonly ICacheItemSerializer<object, TSerialized> _serializer;
 
     /// <summary>
-    /// Initializes a new instance of the <see cref="AsyncSerializingCacheProvider{TResult, TSerialized}"/> class.
+    /// Initializes a new instance of the <see cref="AsyncSerializingCacheProvider{TSerialized}"/> class.
     /// </summary>
     /// <param name="wrappedCacheProvider">The wrapped cache provider.</param>
     /// <param name="serializer">The serializer.</param>

src/Polly/Caching/CacheProviderExtensions.cs

@@ -7,7 +7,7 @@ namespace Polly.Caching;
 public static class CacheProviderExtensions
 {
     /// <summary>
-    /// Provides a strongly <typeparamref name="TCacheFormat"/>-typed version of the supplied <see cref="ISyncCacheProvider"/>
+    /// Provides a strongly <typeparamref name="TCacheFormat"/>-typed version of the supplied <see cref="ISyncCacheProvider"/>.
     /// </summary>
     /// <typeparam name="TCacheFormat">The type the returned <see cref="ISyncCacheProvider{TResult}"/> will handle.</typeparam>
     /// <param name="nonGenericCacheProvider">The non-generic cache provider to wrap.</param>
@@ -16,7 +16,7 @@ public static ISyncCacheProvider<TCacheFormat> For<TCacheFormat>(this ISyncCache
         new GenericCacheProvider<TCacheFormat>(nonGenericCacheProvider);
 
     /// <summary>
-    /// Provides a strongly <typeparamref name="TCacheFormat"/>-typed version of the supplied <see cref="IAsyncCacheProvider"/>
+    /// Provides a strongly <typeparamref name="TCacheFormat"/>-typed version of the supplied <see cref="IAsyncCacheProvider"/>.
     /// </summary>
     /// <typeparam name="TCacheFormat">The type the returned <see cref="IAsyncCacheProvider{TResult}"/> will handle.</typeparam>
     /// <param name="nonGenericCacheProvider">The non-generic cache provider to wrap.</param>

src/Polly/Caching/CacheSyntax.cs

@@ -5,7 +5,7 @@ public partial class Policy
 {
     /// <summary>
     /// <para>Builds a <see cref="Policy"/> that will function like a result cache for delegate executions returning a result.</para>
-    /// <para>Before executing a delegate returning a result, checks whether the <paramref name="cacheProvider"/> holds a value for the cache key specified by <see cref="M:Context.OperationKey"/>.
+    /// <para>Before executing a delegate returning a result, checks whether the <paramref name="cacheProvider"/> holds a value for the cache key specified by <see cref="Context.OperationKey"/>.
     /// If the <paramref name="cacheProvider"/> provides a value from cache, returns that value and does not execute the governed delegate.  If the <paramref name="cacheProvider"/> does not provide a value, executes the governed delegate, stores the value with the <paramref name="cacheProvider"/>, then returns the value.
     /// </para>
     /// </summary>
@@ -19,7 +19,7 @@ public static CachePolicy Cache(ISyncCacheProvider cacheProvider, TimeSpan ttl,
 
     /// <summary>
     /// <para>Builds a <see cref="Policy" /> that will function like a result cache for delegate executions returning a result.</para>
-    /// <para>Before executing a delegate returning a result, checks whether the <paramref name="cacheProvider"/> holds a value for the cache key specified by <see cref="M:Context.OperationKey"/>.
+    /// <para>Before executing a delegate returning a result, checks whether the <paramref name="cacheProvider"/> holds a value for the cache key specified by <see cref="Context.OperationKey"/>.
     /// If the <paramref name="cacheProvider"/> provides a value from cache, returns that value and does not execute the governed delegate.  If the <paramref name="cacheProvider"/> does not provide a value, executes the governed delegate, stores the value with the <paramref name="cacheProvider"/>, then returns the value.
     /// </para>
     /// </summary>

src/Polly/Caching/CacheTResultSyntax.cs

@@ -5,7 +5,7 @@ public partial class Policy
 {
     /// <summary>
     /// <para>Builds a <see cref="Policy{TResult}"/> that will function like a result cache for delegate executions returning a <typeparamref name="TResult"/>.</para>
-    /// <para>Before executing a delegate, checks whether the <paramref name="cacheProvider"/> holds a value for the cache key specified by <see cref="M:Context.OperationKey"/>.
+    /// <para>Before executing a delegate, checks whether the <paramref name="cacheProvider"/> holds a value for the cache key specified by <see cref="Context.OperationKey"/>.
     /// If the <paramref name="cacheProvider"/> provides a value from cache, returns that value and does not execute the governed delegate.  If the <paramref name="cacheProvider"/> does not provide a value, executes the governed delegate, stores the value with the <paramref name="cacheProvider"/>, then returns the value.
     /// </para>
     /// </summary>
@@ -24,7 +24,7 @@ public static CachePolicy<TResult> Cache<TResult>(ISyncCacheProvider cacheProvid
 
     /// <summary>
     /// <para>Builds a <see cref="Policy{TResult}"/> that will function like a result cache for delegate executions returning a <typeparamref name="TResult"/>.</para>
-    /// <para>Before executing a delegate, checks whether the <paramref name="cacheProvider"/> holds a value for the cache key specified by <see cref="M:Context.OperationKey"/>.
+    /// <para>Before executing a delegate, checks whether the <paramref name="cacheProvider"/> holds a value for the cache key specified by <see cref="Context.OperationKey"/>.
     /// If the <paramref name="cacheProvider"/> provides a value from cache, returns that value and does not execute the governed delegate.  If the <paramref name="cacheProvider"/> does not provide a value, executes the governed delegate, stores the value with the <paramref name="cacheProvider"/>, then returns the value.
     /// </para>
     /// </summary>
@@ -343,7 +343,7 @@ public static CachePolicy<TResult> Cache<TResult>(
 
     /// <summary>
     /// <para>Builds a <see cref="Policy{TResult}"/> that will function like a result cache for delegate executions returning a <typeparamref name="TResult"/>.</para>
-    /// <para>Before executing a delegate, checks whether the <paramref name="cacheProvider"/> holds a value for the cache key specified by <see cref="M:Context.OperationKey"/>.
+    /// <para>Before executing a delegate, checks whether the <paramref name="cacheProvider"/> holds a value for the cache key specified by <see cref="Context.OperationKey"/>.
     /// If the <paramref name="cacheProvider"/> provides a value from cache, returns that value and does not execute the governed delegate.  If the <paramref name="cacheProvider"/> does not provide a value, executes the governed delegate, stores the value with the <paramref name="cacheProvider"/>, then returns the value.
     /// </para>
     /// </summary>
@@ -357,7 +357,7 @@ public static CachePolicy<TResult> Cache<TResult>(ISyncCacheProvider<TResult> ca
 
     /// <summary>
     /// <para>Builds a <see cref="Policy{TResult}"/> that will function like a result cache for delegate executions returning a <typeparamref name="TResult"/>.</para>
-    /// <para>Before executing a delegate, checks whether the <paramref name="cacheProvider"/> holds a value for the cache key specified by <see cref="M:Context.OperationKey"/>.
+    /// <para>Before executing a delegate, checks whether the <paramref name="cacheProvider"/> holds a value for the cache key specified by <see cref="Context.OperationKey"/>.
     /// If the <paramref name="cacheProvider"/> provides a value from cache, returns that value and does not execute the governed delegate.  If the <paramref name="cacheProvider"/> does not provide a value, executes the governed delegate, stores the value with the <paramref name="cacheProvider"/>, then returns the value.
     /// </para>
     /// </summary>
@@ -372,7 +372,7 @@ public static CachePolicy<TResult> Cache<TResult>(ISyncCacheProvider<TResult> ca
 
     /// <summary>
     /// <para>Builds a <see cref="Policy{TResult}"/> that will function like a result cache for delegate executions returning a <typeparamref name="TResult"/>.</para>
-    /// <para>Before executing a delegate, checks whether the <paramref name="cacheProvider"/> holds a value for the cache key specified by <see cref="M:Context.OperationKey"/>.
+    /// <para>Before executing a delegate, checks whether the <paramref name="cacheProvider"/> holds a value for the cache key specified by <see cref="Context.OperationKey"/>.
     /// If the <paramref name="cacheProvider"/> provides a value from cache, returns that value and does not execute the governed delegate.  If the <paramref name="cacheProvider"/> does not provide a value, executes the governed delegate, stores the value with the <paramref name="cacheProvider"/>, then returns the value.
     /// </para>
     /// </summary>

src/Polly/Caching/DefaultCacheKeyStrategy.cs

@@ -2,15 +2,15 @@
 namespace Polly.Caching;
 
 /// <summary>
-/// The default cache key strategy for <see cref="CachePolicy"/>.  Returns the property <see cref="M:Context.OperationKey"/>.
+/// The default cache key strategy for <see cref="CachePolicy"/>.  Returns the property <see cref="Context.OperationKey"/>.
 /// </summary>
 public class DefaultCacheKeyStrategy : ICacheKeyStrategy
 {
     /// <summary>
     /// Gets the cache key from the given execution context.
     /// </summary>
     /// <param name="context">The execution context.</param>
-    /// <returns>The cache key</returns>
+    /// <returns>The cache key.</returns>
     public string GetCacheKey(Context context) =>
         context.OperationKey;
 

src/Polly/Caching/ICacheItemSerializer.cs

@@ -12,13 +12,13 @@ public interface ICacheItemSerializer<TResult, TSerialized>
     /// Serializes the specified object.
     /// </summary>
     /// <param name="objectToSerialize">The object to serialize.</param>
-    /// <returns>The serialized object</returns>
+    /// <returns>The serialized object.</returns>
     TSerialized? Serialize(TResult? objectToSerialize);
 
     /// <summary>
     /// Deserializes the specified object.
     /// </summary>
     /// <param name="objectToDeserialize">The object to deserialize.</param>
-    /// <returns>The deserialized object</returns>
+    /// <returns>The deserialized object.</returns>
     TResult? Deserialize(TSerialized? objectToDeserialize);
 }