Fix SA1615/SA1623 warnings (#2091)

Fix SA1615 & SA1623 warnings.

src/Polly/AsyncPolicy.ContextAndKeys.cs

@@ -7,6 +7,7 @@ public abstract partial class AsyncPolicy
  /// <remarks>Must be called before the policy is first used. Can only be set once.</remarks>
  /// </summary>
  /// <param name="policyKey">The unique, used-definable key to assign to this <see cref="AsyncPolicy"/> instance.</param>
+ /// <returns>An instance of <see cref="AsyncPolicy"/>.</returns>
  public AsyncPolicy WithPolicyKey(string policyKey)
  {
  if (policyKeyInternal != null)
@@ -23,6 +24,7 @@ public AsyncPolicy WithPolicyKey(string policyKey)
  /// <remarks>Must be called before the policy is first used. Can only be set once.</remarks>
  /// </summary>
  /// <param name="policyKey">The unique, used-definable key to assign to this <see cref="IAsyncPolicy"/> instance.</param>
+ /// <returns>An instance of <see cref="IAsyncPolicy"/>.</returns>
  IAsyncPolicy IAsyncPolicy.WithPolicyKey(string policyKey)
  {
  if (policyKeyInternal != null)
@@ -42,6 +44,7 @@ public abstract partial class AsyncPolicy<TResult>
  /// <remarks>Must be called before the policy is first used. Can only be set once.</remarks>
  /// </summary>
  /// <param name="policyKey">The unique, used-definable key to assign to this <see cref="AsyncPolicy{TResult}"/> instance.</param>
+ /// <returns>An instance of <see cref="AsyncPolicy{TResult}"/>.</returns>
  public AsyncPolicy<TResult> WithPolicyKey(string policyKey)
  {
  if (policyKeyInternal != null)
@@ -58,6 +61,7 @@ public AsyncPolicy<TResult> WithPolicyKey(string policyKey)
  /// <remarks>Must be called before the policy is first used. Can only be set once.</remarks>
  /// </summary>
  /// <param name="policyKey">The unique, used-definable key to assign to this <see cref="IAsyncPolicy{TResult}"/> instance.</param>
+ /// <returns>An instance of <see cref="IAsyncPolicy{TResult}"/>.</returns>
  IAsyncPolicy<TResult> IAsyncPolicy<TResult>.WithPolicyKey(string policyKey)
  {
  if (policyKeyInternal != null)

src/Polly/AsyncPolicy.ExecuteOverloads.cs

@@ -8,6 +8,7 @@ public abstract partial class AsyncPolicy : PolicyBase, IAsyncPolicy
  /// Executes the specified asynchronous action within the policy.
  /// </summary>
  /// <param name="action">The action to perform.</param>
+ /// <returns>A <see cref="Task" /> which completes when <see cref="AsyncPolicy"/> is registered.</returns>
  [DebuggerStepThrough]
  public Task ExecuteAsync(Func<Task> action) =>
  ExecuteAsync((_, _) => action(), [], DefaultCancellationToken, DefaultContinueOnCapturedContext);
@@ -17,6 +18,7 @@ public Task ExecuteAsync(Func<Task> action) =>
  /// </summary>
  /// <param name="action">The action to perform.</param>
  /// <param name="contextData">Arbitrary data that is passed to the exception policy.</param>
+ /// <returns>A <see cref="Task" /> which completes when <see cref="AsyncPolicy"/> is registered.</returns>
  [DebuggerStepThrough]
  public Task ExecuteAsync(Func<Context, Task> action, IDictionary<string, object> contextData) =>
  ExecuteAsync((ctx, _) => action(ctx), new Context(contextData), DefaultCancellationToken, DefaultContinueOnCapturedContext);
@@ -26,6 +28,7 @@ public Task ExecuteAsync(Func<Context, Task> action, IDictionary<string, object>
  /// </summary>
  /// <param name="action">The action to perform.</param>
  /// <param name="context">Context data that is passed to the exception policy.</param>
+ /// <returns>A <see cref="Task" /> which completes when <see cref="AsyncPolicy"/> is registered.</returns>
  [DebuggerStepThrough]
  public Task ExecuteAsync(Func<Context, Task> action, Context context) =>
  ExecuteAsync((ctx, _) => action(ctx), context, DefaultCancellationToken, DefaultContinueOnCapturedContext);
@@ -35,6 +38,7 @@ public Task ExecuteAsync(Func<Context, Task> action, Context context) =>
  /// </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>A <see cref="Task" /> which completes when <see cref="AsyncPolicy"/> is registered.</returns>
  [DebuggerStepThrough]
  public Task ExecuteAsync(Func<CancellationToken, Task> action, CancellationToken cancellationToken) =>
  ExecuteAsync((_, ct) => action(ct), [], cancellationToken, DefaultContinueOnCapturedContext);
@@ -45,6 +49,7 @@ public Task ExecuteAsync(Func<CancellationToken, Task> action, 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>
+ /// <returns>A <see cref="Task" /> which completes when <see cref="AsyncPolicy"/> is registered.</returns>
  [DebuggerStepThrough]
  public Task ExecuteAsync(Func<Context, CancellationToken, Task> action, IDictionary<string, object> contextData, CancellationToken cancellationToken) =>
  ExecuteAsync(action, new Context(contextData), cancellationToken, DefaultContinueOnCapturedContext);
@@ -55,6 +60,7 @@ public Task ExecuteAsync(Func<Context, CancellationToken, Task> action, IDiction
  /// <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>A <see cref="Task" /> which completes when <see cref="AsyncPolicy"/> is registered.</returns>
  [DebuggerStepThrough]
  public Task ExecuteAsync(Func<Context, CancellationToken, Task> action, Context context, CancellationToken cancellationToken) =>
  ExecuteAsync(action, context, cancellationToken, DefaultContinueOnCapturedContext);
@@ -66,6 +72,7 @@ public Task ExecuteAsync(Func<Context, CancellationToken, Task> action, Context
  /// <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>
  /// <exception cref="InvalidOperationException">Please use asynchronous-defined policies when calling asynchronous ExecuteAsync (and similar) methods.</exception>
+ /// <returns>A <see cref="Task" /> which completes when <see cref="AsyncPolicy"/> is registered.</returns>
  [DebuggerStepThrough]
  public Task ExecuteAsync(Func<CancellationToken, Task> action, CancellationToken cancellationToken, bool continueOnCapturedContext) =>
  ExecuteAsync((_, ct) => action(ct), [], cancellationToken, continueOnCapturedContext);
@@ -78,6 +85,7 @@ public Task ExecuteAsync(Func<CancellationToken, Task> action, CancellationToken
  /// <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>
  /// <exception cref="ArgumentNullException">Thrown when <paramref name="contextData"/> is <see langword="null"/>.</exception>
+ /// <returns>A <see cref="Task" /> which completes when <see cref="AsyncPolicy"/> is registered.</returns>
  [DebuggerStepThrough]
  public Task ExecuteAsync(Func<Context, CancellationToken, Task> action, IDictionary<string, object> contextData, CancellationToken cancellationToken, bool continueOnCapturedContext) =>
  ExecuteAsync(action, new Context(contextData), cancellationToken, continueOnCapturedContext);
@@ -90,6 +98,7 @@ public Task ExecuteAsync(Func<Context, CancellationToken, Task> action, IDiction
  /// <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>
  /// <exception cref="InvalidOperationException">Please use asynchronous-defined policies when calling asynchronous ExecuteAsync (and similar) methods.</exception>
+ /// <returns>A <see cref="Task" /> which completes when <see cref="AsyncPolicy"/> is registered.</returns>
  [DebuggerStepThrough]
  public async Task ExecuteAsync(Func<Context, CancellationToken, Task> action, Context context, CancellationToken cancellationToken, bool continueOnCapturedContext)
  {
@@ -277,6 +286,7 @@ public Task<PolicyResult> ExecuteAndCaptureAsync(Func<Context, Task> action, Con
  /// </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>
  [DebuggerStepThrough]
  public Task<PolicyResult> ExecuteAndCaptureAsync(Func<CancellationToken, Task> action, CancellationToken cancellationToken) =>
  ExecuteAndCaptureAsync((_, ct) => action(ct), [], cancellationToken, DefaultContinueOnCapturedContext);
@@ -299,6 +309,7 @@ public Task<PolicyResult> ExecuteAndCaptureAsync(Func<Context, CancellationToken
  /// <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>
  [DebuggerStepThrough]
  public Task<PolicyResult> ExecuteAndCaptureAsync(Func<Context, CancellationToken, Task> action, Context context, CancellationToken cancellationToken) =>
  ExecuteAndCaptureAsync(action, context, cancellationToken, DefaultContinueOnCapturedContext);
@@ -310,6 +321,7 @@ public Task<PolicyResult> ExecuteAndCaptureAsync(Func<Context, CancellationToken
  /// <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>
  /// <exception cref="InvalidOperationException">Please use asynchronous-defined policies when calling asynchronous ExecuteAsync (and similar) methods.</exception>
+ /// <returns>The captured result.</returns>
  [DebuggerStepThrough]
  public Task<PolicyResult> ExecuteAndCaptureAsync(Func<CancellationToken, Task> action, CancellationToken cancellationToken, bool continueOnCapturedContext) =>
  ExecuteAndCaptureAsync((_, ct) => action(ct), [], cancellationToken, continueOnCapturedContext);
@@ -335,6 +347,7 @@ public Task<PolicyResult> ExecuteAndCaptureAsync(Func<Context, CancellationToken
  /// <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>
  /// <exception cref="InvalidOperationException">Please use asynchronous-defined policies when calling asynchronous ExecuteAsync (and similar) methods.</exception>
+ /// <returns>The captured result.</returns>
  [DebuggerStepThrough]
  public async Task<PolicyResult> ExecuteAndCaptureAsync(Func<Context, CancellationToken, Task> action, Context context, CancellationToken cancellationToken, bool continueOnCapturedContext)
  {

src/Polly/Context.cs

@@ -25,24 +25,25 @@ public Context()
  }
 
  /// <summary>
+ /// Gets the wrapped <see cref="PolicyBase.PolicyKey"/>.
  /// When execution is through a <see cref="PolicyWrap"/>, identifies the PolicyWrap executing the current delegate by returning the <see cref="PolicyBase.PolicyKey"/> of the outermost layer in the PolicyWrap; otherwise, null.
  /// </summary>
  public string PolicyWrapKey { get; internal set; }
 
  /// <summary>
- /// The <see cref="PolicyBase.PolicyKey"/> of the policy instance executing the current delegate.
+ /// Gets the <see cref="PolicyBase.PolicyKey"/> of the policy instance executing the current delegate.
  /// </summary>
  public string PolicyKey { get; internal set; }
 
  /// <summary>
- /// A key unique to the call site of the current execution.
+ /// Gets a key unique to the call site of the current execution.
  /// <remarks>Policy instances are commonly reused across multiple call sites. Set an OperationKey so that logging and metrics can distinguish usages of policy instances at different call sites.</remarks>
  /// <remarks>The value is set by using the <see cref="Context(string)"/> constructor taking an operationKey parameter.</remarks>
  /// </summary>
  public string OperationKey { get; }
 
  /// <summary>
- /// A Guid guaranteed to be unique to each execution.
+ /// Gets a GUID guaranteed to be unique to each execution.
  /// <remarks>Acts as a correlation id so that events specific to a single execution can be identified in logging and telemetry.</remarks>
  /// </summary>
  public Guid CorrelationId

src/Polly/DelegateResult.cs

@@ -20,12 +20,12 @@ public DelegateResult(Exception exception) =>
  Exception = exception;
 
  /// <summary>
- /// The result of executing the delegate. Will be default(TResult) if an exception was thrown.
+ /// Gets the result of executing the delegate. Will be default(TResult) if an exception was thrown.
  /// </summary>
  public TResult Result { get; }
 
  /// <summary>
- /// Any exception thrown while executing the delegate. Will be null if policy executed without exception.
+ /// Gets the exception thrown while executing the delegate. Will be null if policy executed without exception.
  /// </summary>
  public Exception Exception { get; }
 }

src/Polly/IAsyncPolicy.TResult.cs

@@ -11,6 +11,7 @@ public interface IAsyncPolicy<TResult> : IsPolicy
  /// <remarks>Must be called before the policy is first used. Can only be set once.</remarks>
  /// </summary>
  /// <param name="policyKey">The unique, used-definable key to assign to this <see cref="IAsyncPolicy{TResult}"/> instance.</param>
+ /// <returns>An instance of <see cref="IAsyncPolicy{TResult}"/>.</returns>
  IAsyncPolicy<TResult> WithPolicyKey(string policyKey);
 
  /// <summary>