Cleanup XML comments (#2007)

* Fix SA1629 for ArgumentNullException XML comments

* Fix "CA1200: Avoid using cref tags with a prefix" for ArgumentNullException

* Fix SA1629 and unify ArgumentNullException style

* Fix "SA1627 The documentation text within the 'exception' tag should not be empty"

* Unify ArgumentNullException XML comment style

* Fix SA1629 in remarks (are they even neccessary?)

* Unify ArgumentNullException XML comment style

* Fix SA1629 and unify XML comments in ArgumentNullException with two params; and fix wrongly referenced parameters in comments

* Fix SA1629 and unify comments in returns tag
Fix SA1629 in ArgumentOutOfRangeException XML comments and an summary tags

* Fix SA1614 "Element parameter documentation should have text"

* Fix SA1629 in param and returns tags
Fix SA1611 "The documentation for parameter 'key' is missing"

* Fix more SA1629; fixed some incorrect and added missing param comments

* PR comments (fix tag order, parameter name, remove duplicates)

src/Polly.Core/ResiliencePipelineBuilderExtensions.cs

@@ -16,7 +16,7 @@ public static class ResiliencePipelineBuilderExtensions
     /// <param name="builder">The builder instance.</param>
     /// <param name="pipeline">The pipeline instance.</param>
     /// <returns>The same builder instance.</returns>
-    /// <exception cref="ArgumentNullException">Thrown when <paramref name="pipeline"/> is null.</exception>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="pipeline"/> is <see langword="null"/>.</exception>
     /// <exception cref="InvalidOperationException">Thrown when this builder was already used to create a pipeline. The builder cannot be modified after it has been used.</exception>
     [UnconditionalSuppressMessage(
         "Trimming",
@@ -39,7 +39,7 @@ public static TBuilder AddPipeline<TBuilder>(this TBuilder builder, ResiliencePi
     /// <param name="builder">The builder instance.</param>
     /// <param name="pipeline">The pipeline instance.</param>
     /// <returns>The same builder instance.</returns>
-    /// <exception cref="ArgumentNullException">Thrown when <paramref name="pipeline"/> is null.</exception>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="pipeline"/> is <see langword="null"/>.</exception>
     /// <exception cref="InvalidOperationException">Thrown when this builder was already used to create a strategy. The builder cannot be modified after it has been used.</exception>
     [UnconditionalSuppressMessage(
         "Trimming",

src/Polly/AsyncPolicy.TResult.ExecuteOverloads.cs

@@ -8,7 +8,7 @@ public abstract partial class AsyncPolicy<TResult> : IAsyncPolicy<TResult>
     ///     Executes the specified asynchronous action within the policy and returns the result.
     /// </summary>
     /// <param name="action">The action to perform.</param>
-    /// <returns>The value returned by the action</returns>
+    /// <returns>The value returned by the action.</returns>
     [DebuggerStepThrough]
     public Task<TResult> ExecuteAsync(Func<Task<TResult>> action) =>
         ExecuteAsync((_, _) => action(), [], CancellationToken.None, DefaultContinueOnCapturedContext);
@@ -18,7 +18,7 @@ public Task<TResult> ExecuteAsync(Func<Task<TResult>> action) =>
     /// </summary>
     /// <param name="action">The action to perform.</param>
     /// <param name="contextData">Arbitrary data that is passed to the exception policy.</param>
-    /// <returns>The value returned by the action</returns>
+    /// <returns>The value returned by the action.</returns>
     [DebuggerStepThrough]
     public Task<TResult> ExecuteAsync(Func<Context, Task<TResult>> action, IDictionary<string, object> contextData) =>
         ExecuteAsync((ctx, _) => action(ctx), new Context(contextData), CancellationToken.None, DefaultContinueOnCapturedContext);
@@ -28,7 +28,7 @@ public Task<TResult> ExecuteAsync(Func<Context, Task<TResult>> action, IDictiona
     /// </summary>
     /// <param name="action">The action to perform.</param>
     /// <param name="context">Context data that is passed to the exception policy.</param>
-    /// <returns>The value returned by the action</returns>
+    /// <returns>The value returned by the action.</returns>
     [DebuggerStepThrough]
     public Task<TResult> ExecuteAsync(Func<Context, Task<TResult>> action, Context context) =>
         ExecuteAsync((ctx, _) => action(ctx), context, CancellationToken.None, DefaultContinueOnCapturedContext);
@@ -38,7 +38,7 @@ public Task<TResult> ExecuteAsync(Func<Context, Task<TResult>> action, Context c
     /// </summary>
     /// <param name="action">The action to perform.</param>
     /// <param name="cancellationToken">A cancellation token which can be used to cancel the action.  When a retry policy is in use, also cancels any further retries.</param>
-    /// <returns>The value returned by the action</returns>
+    /// <returns>The value returned by the action.</returns>
     [DebuggerStepThrough]
     public Task<TResult> ExecuteAsync(Func<CancellationToken, Task<TResult>> action, CancellationToken cancellationToken) =>
         ExecuteAsync((_, ct) => action(ct), [], cancellationToken, DefaultContinueOnCapturedContext);
@@ -49,7 +49,7 @@ public Task<TResult> ExecuteAsync(Func<CancellationToken, Task<TResult>> action,
     /// <param name="action">The action to perform.</param>
     /// <param name="continueOnCapturedContext">Whether to continue on a captured synchronization context.</param>
     /// <param name="cancellationToken">A cancellation token which can be used to cancel the action.  When a retry policy is in use, also cancels any further retries.</param>
-    /// <returns>The value returned by the action</returns>
+    /// <returns>The value returned by the action.</returns>
     /// <exception cref="InvalidOperationException">Please use asynchronous-defined policies when calling asynchronous ExecuteAsync (and similar) methods.</exception>
     [DebuggerStepThrough]
     public Task<TResult> ExecuteAsync(Func<CancellationToken, Task<TResult>> action, CancellationToken cancellationToken, bool continueOnCapturedContext) =>
@@ -61,7 +61,7 @@ public Task<TResult> ExecuteAsync(Func<CancellationToken, Task<TResult>> action,
     /// <param name="action">The action to perform.</param>
     /// <param name="contextData">Arbitrary data that is passed to the exception policy.</param>
     /// <param name="cancellationToken">A cancellation token which can be used to cancel the action.  When a retry policy in use, also cancels any further retries.</param>
-    /// <returns>The value returned by the action</returns>
+    /// <returns>The value returned by the action.</returns>
     [DebuggerStepThrough]
     public Task<TResult> ExecuteAsync(Func<Context, CancellationToken, Task<TResult>> action, IDictionary<string, object> contextData, CancellationToken cancellationToken) =>
         ExecuteAsync(action, new Context(contextData), cancellationToken, DefaultContinueOnCapturedContext);
@@ -72,7 +72,7 @@ public Task<TResult> ExecuteAsync(Func<Context, CancellationToken, Task<TResult>
     /// <param name="action">The action to perform.</param>
     /// <param name="context">Context data that is passed to the exception policy.</param>
     /// <param name="cancellationToken">A cancellation token which can be used to cancel the action.  When a retry policy is in use, also cancels any further retries.</param>
-    /// <returns>The value returned by the action</returns>
+    /// <returns>The value returned by the action.</returns>
     [DebuggerStepThrough]
     public Task<TResult> ExecuteAsync(Func<Context, CancellationToken, Task<TResult>> action, Context context, CancellationToken cancellationToken) =>
         ExecuteAsync(action, context, cancellationToken, DefaultContinueOnCapturedContext);
@@ -84,8 +84,8 @@ public Task<TResult> ExecuteAsync(Func<Context, CancellationToken, Task<TResult>
     /// <param name="contextData">Arbitrary data that is passed to the exception policy.</param>
     /// <param name="cancellationToken">A cancellation token which can be used to cancel the action.  When a retry policy in use, also cancels any further retries.</param>
     /// <param name="continueOnCapturedContext">Whether to continue on a captured synchronization context.</param>
-    /// <returns>The value returned by the action</returns>
-    /// <exception cref="ArgumentNullException">contextData</exception>
+    /// <returns>The value returned by the action.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="contextData"/> is <see langword="null"/>.</exception>
     [DebuggerStepThrough]
     public Task<TResult> ExecuteAsync(Func<Context, CancellationToken, Task<TResult>> action, IDictionary<string, object> contextData, CancellationToken cancellationToken, bool continueOnCapturedContext) =>
         ExecuteAsync(action, new Context(contextData), cancellationToken, continueOnCapturedContext);
@@ -97,7 +97,7 @@ public Task<TResult> ExecuteAsync(Func<Context, CancellationToken, Task<TResult>
     /// <param name="context">Context data that is passed to the exception policy.</param>
     /// <param name="continueOnCapturedContext">Whether to continue on a captured synchronization context.</param>
     /// <param name="cancellationToken">A cancellation token which can be used to cancel the action.  When a retry policy is in use, also cancels any further retries.</param>
-    /// <returns>The value returned by the action</returns>
+    /// <returns>The value returned by the action.</returns>
     /// <exception cref="InvalidOperationException">Please use asynchronous-defined policies when calling asynchronous ExecuteAsync (and similar) methods.</exception>
     [DebuggerStepThrough]
     public async Task<TResult> ExecuteAsync(Func<Context, CancellationToken, Task<TResult>> action, Context context, CancellationToken cancellationToken, bool continueOnCapturedContext)
@@ -125,7 +125,7 @@ public async Task<TResult> ExecuteAsync(Func<Context, CancellationToken, Task<TR
     /// Executes the specified asynchronous action within the policy and returns the result.
     /// </summary>
     /// <param name="action">The action to perform.</param>
-    /// <returns>The captured result</returns>
+    /// <returns>The captured result.</returns>
     [DebuggerStepThrough]
     public Task<PolicyResult<TResult>> ExecuteAndCaptureAsync(Func<Task<TResult>> action) =>
         ExecuteAndCaptureAsync((_, _) => action(), [], CancellationToken.None, DefaultContinueOnCapturedContext);
@@ -135,8 +135,8 @@ public Task<PolicyResult<TResult>> ExecuteAndCaptureAsync(Func<Task<TResult>> ac
     /// </summary>
     /// <param name="action">The action to perform.</param>
     /// <param name="contextData">Arbitrary data that is passed to the exception policy.</param>
-    /// <exception cref="ArgumentNullException">contextData</exception>
-    /// <returns>The captured result</returns>
+    /// <returns>The captured result.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="contextData"/> is <see langword="null"/>.</exception>
     [DebuggerStepThrough]
     public Task<PolicyResult<TResult>> ExecuteAndCaptureAsync(Func<Context, Task<TResult>> action, IDictionary<string, object> contextData) =>
         ExecuteAndCaptureAsync((ctx, _) => action(ctx), new Context(contextData), CancellationToken.None, DefaultContinueOnCapturedContext);
@@ -146,7 +146,7 @@ public Task<PolicyResult<TResult>> ExecuteAndCaptureAsync(Func<Context, Task<TRe
     /// </summary>
     /// <param name="action">The action to perform.</param>
     /// <param name="context">Context data that is passed to the exception policy.</param>
-    /// <returns>The captured result</returns>
+    /// <returns>The captured result.</returns>
     [DebuggerStepThrough]
     public Task<PolicyResult<TResult>> ExecuteAndCaptureAsync(Func<Context, Task<TResult>> action, Context context) =>
         ExecuteAndCaptureAsync((ctx, _) => action(ctx), context, CancellationToken.None, DefaultContinueOnCapturedContext);
@@ -156,7 +156,7 @@ public Task<PolicyResult<TResult>> ExecuteAndCaptureAsync(Func<Context, Task<TRe
     /// </summary>
     /// <param name="action">The action to perform.</param>
     /// <param name="cancellationToken">A cancellation token which can be used to cancel the action.  When a retry policy in use, also cancels any further retries.</param>
-    /// <returns>The captured result</returns>
+    /// <returns>The captured result.</returns>
     [DebuggerStepThrough]
     public Task<PolicyResult<TResult>> ExecuteAndCaptureAsync(Func<CancellationToken, Task<TResult>> action, CancellationToken cancellationToken) =>
         ExecuteAndCaptureAsync((_, ct) => action(ct), [], cancellationToken, DefaultContinueOnCapturedContext);
@@ -167,7 +167,7 @@ public Task<PolicyResult<TResult>> ExecuteAndCaptureAsync(Func<CancellationToken
     /// <param name="action">The action to perform.</param>
     /// <param name="continueOnCapturedContext">Whether to continue on a captured synchronization context.</param>
     /// <param name="cancellationToken">A cancellation token which can be used to cancel the action.  When a retry policy in use, also cancels any further retries.</param>
-    /// <returns>The captured result</returns>
+    /// <returns>The captured result.</returns>
     /// <exception cref="InvalidOperationException">Please use asynchronous-defined policies when calling asynchronous ExecuteAsync (and similar) methods.</exception>
     [DebuggerStepThrough]
     public Task<PolicyResult<TResult>> ExecuteAndCaptureAsync(Func<CancellationToken, Task<TResult>> action, CancellationToken cancellationToken, bool continueOnCapturedContext) =>
@@ -179,8 +179,8 @@ public Task<PolicyResult<TResult>> ExecuteAndCaptureAsync(Func<CancellationToken
     /// <param name="action">The action to perform.</param>
     /// <param name="contextData">Arbitrary data that is passed to the exception policy.</param>
     /// <param name="cancellationToken">A cancellation token which can be used to cancel the action.  When a retry policy in use, also cancels any further retries.</param>
-    /// <exception cref="ArgumentNullException">contextData</exception>
-    /// <returns>The captured result</returns>
+    /// <returns>The captured result.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="contextData"/> is <see langword="null"/>.</exception>
     [DebuggerStepThrough]
     public Task<PolicyResult<TResult>> ExecuteAndCaptureAsync(Func<Context, CancellationToken, Task<TResult>> action, IDictionary<string, object> contextData, CancellationToken cancellationToken) =>
         ExecuteAndCaptureAsync(action, new Context(contextData), cancellationToken, DefaultContinueOnCapturedContext);
@@ -191,7 +191,7 @@ public Task<PolicyResult<TResult>> ExecuteAndCaptureAsync(Func<Context, Cancella
     /// <param name="action">The action to perform.</param>
     /// <param name="context">Context data that is passed to the exception policy.</param>
     /// <param name="cancellationToken">A cancellation token which can be used to cancel the action.  When a retry policy in use, also cancels any further retries.</param>
-    /// <returns>The captured result</returns>
+    /// <returns>The captured result.</returns>
     [DebuggerStepThrough]
     public Task<PolicyResult<TResult>> ExecuteAndCaptureAsync(Func<Context, CancellationToken, Task<TResult>> action, Context context, CancellationToken cancellationToken) =>
         ExecuteAndCaptureAsync(action, context, cancellationToken, DefaultContinueOnCapturedContext);
@@ -203,8 +203,8 @@ public Task<PolicyResult<TResult>> ExecuteAndCaptureAsync(Func<Context, Cancella
     /// <param name="contextData">Arbitrary data that is passed to the exception policy.</param>
     /// <param name="continueOnCapturedContext">Whether to continue on a captured synchronization context.</param>
     /// <param name="cancellationToken">A cancellation token which can be used to cancel the action.  When a retry policy in use, also cancels any further retries.</param>
-    /// <returns>The captured result</returns>
-    /// <exception cref="ArgumentNullException">contextData</exception>
+    /// <returns>The captured result.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="contextData"/> is <see langword="null"/>.</exception>
     [DebuggerStepThrough]
     public Task<PolicyResult<TResult>> ExecuteAndCaptureAsync(Func<Context, CancellationToken, Task<TResult>> action, IDictionary<string, object> contextData, CancellationToken cancellationToken, bool continueOnCapturedContext) =>
         ExecuteAndCaptureAsync(action, new Context(contextData), cancellationToken, continueOnCapturedContext);
@@ -216,7 +216,7 @@ public Task<PolicyResult<TResult>> ExecuteAndCaptureAsync(Func<Context, Cancella
     /// <param name="context">Context data that is passed to the exception policy.</param>
     /// <param name="continueOnCapturedContext">Whether to continue on a captured synchronization context.</param>
     /// <param name="cancellationToken">A cancellation token which can be used to cancel the action.  When a retry policy in use, also cancels any further retries.</param>
-    /// <returns>The captured result</returns>
+    /// <returns>The captured result.</returns>
     /// <exception cref="InvalidOperationException">Please use asynchronous-defined policies when calling asynchronous ExecuteAsync (and similar) methods.</exception>
     [DebuggerStepThrough]
     public async Task<PolicyResult<TResult>> ExecuteAndCaptureAsync(Func<Context, CancellationToken, Task<TResult>> action, Context context, CancellationToken cancellationToken, bool continueOnCapturedContext)

src/Polly/AsyncPolicy.TResult.cs

@@ -2,7 +2,7 @@
 namespace Polly;
 
 /// <summary>
-/// Transient exception handling policies that can be applied to asynchronous delegates
+/// Transient exception handling policies that can be applied to asynchronous delegates.
 /// </summary>
 /// <typeparam name="TResult">The return type of delegates which may be executed through the policy.</typeparam>
 public abstract partial class AsyncPolicy<TResult> : PolicyBase<TResult>

src/Polly/AsyncPolicy.cs

@@ -2,7 +2,7 @@
 namespace Polly;
 
 /// <summary>
-/// Transient exception handling policies that can be applied to asynchronous delegates
+/// Transient exception handling policies that can be applied to asynchronous delegates.
 /// </summary>
 public abstract partial class AsyncPolicy
 {

src/Polly/Bulkhead/AsyncBulkheadSyntax.cs

@@ -23,7 +23,7 @@ public static AsyncBulkheadPolicy BulkheadAsync(int maxParallelization)
     /// <param name="onBulkheadRejectedAsync">An action to call asynchronously, if the bulkhead rejects execution due to oversubscription.</param>
     /// <returns>The policy instance.</returns>
     /// <exception cref="ArgumentOutOfRangeException">maxParallelization;Value must be greater than zero.</exception>
-    /// <exception cref="ArgumentNullException">onBulkheadRejectedAsync</exception>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="onBulkheadRejectedAsync"/> is <see langword="null"/>.</exception>
     /// <returns>The policy instance.</returns>
     public static AsyncBulkheadPolicy BulkheadAsync(int maxParallelization, Func<Context, Task> onBulkheadRejectedAsync) =>
         BulkheadAsync(maxParallelization, 0, onBulkheadRejectedAsync);
@@ -53,7 +53,7 @@ public static AsyncBulkheadPolicy BulkheadAsync(int maxParallelization, int maxQ
     /// <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">onBulkheadRejectedAsync</exception>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="onBulkheadRejectedAsync"/> is <see langword="null"/>.</exception>
     public static AsyncBulkheadPolicy BulkheadAsync(
         int maxParallelization,
         int maxQueuingActions,