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>