Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Xml comments cleanup and improvement #2007

Merged
merged 13 commits into from
Mar 5, 2024
Merged

Xml comments cleanup and improvement #2007

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
a18e456
Fix SA1629 for ArgumentNullException XML comments
gintsk Mar 3, 2024
d343447
Fix "CA1200: Avoid using cref tags with a prefix" for ArgumentNullExc…
gintsk Mar 3, 2024
51af212
Fix SA1629 and unify ArgumentNullException style
gintsk Mar 3, 2024
47ade1e
Fix "SA1627 The documentation text within the 'exception' tag should …
gintsk Mar 3, 2024
2c15316
Unify ArgumentNullException XML comment style
gintsk Mar 3, 2024
997420a
Fix SA1629 in remarks (are they even neccessary?)
gintsk Mar 3, 2024
386dd7e
Unify ArgumentNullException XML comment style
gintsk Mar 3, 2024
4e9e28f
Fix SA1629 and unify XML comments in ArgumentNullException with two p…
gintsk Mar 3, 2024
caacb3e
Fix SA1629 and unify comments in returns tag
gintsk Mar 3, 2024
9d6de3f
Fix SA1614 "Element parameter documentation should have text"
gintsk Mar 3, 2024
a68b4aa
Fix SA1629 in param and returns tags
gintsk Mar 3, 2024
a50ef2b
Fix more SA1629; fixed some incorrect and added missing param comments
gintsk Mar 3, 2024
e18de1a
PR comments (fix tag order, parameter name, remove duplicates)
gintsk Mar 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions src/Polly.Core/ResiliencePipelineBuilderExtensions.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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",
Expand Down
64 changes: 32 additions & 32 deletions src/Polly/AsyncPolicy.ExecuteOverloads.cs
View file
Open in desktop

Large diffs are not rendered by default.

44 changes: 22 additions & 22 deletions src/Polly/AsyncPolicy.TResult.ExecuteOverloads.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand All @@ -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);
Expand All @@ -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);
Expand All @@ -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);
Expand All @@ -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) =>
Expand All @@ -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);
Expand All @@ -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);
Expand All @@ -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);
Expand All @@ -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)
Expand Down Expand Up @@ -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);
Expand All @@ -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);
Expand All @@ -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);
Expand All @@ -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);
Expand All @@ -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) =>
Expand All @@ -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);
Expand All @@ -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);
Expand All @@ -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);
Expand All @@ -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)
Expand Down
2 changes: 1 addition & 1 deletion src/Polly/AsyncPolicy.TResult.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
2 changes: 1 addition & 1 deletion src/Polly/AsyncPolicy.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
{
Expand Down
4 changes: 2 additions & 2 deletions src/Polly/Bulkhead/AsyncBulkheadSyntax.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down Expand Up @@ -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,
Expand Down
Loading