improve docs

Author: martintmk

src/Polly.Core/CircuitBreaker/OnCircuitClosedArguments.cs

@@ -5,6 +5,9 @@ namespace Polly.CircuitBreaker;
 /// <summary>
 /// Arguments used by <see cref="CircuitBreakerStrategyOptions{TResult}.OnClosed"/> event.
 /// </summary>
+/// <remarks>
+/// Always use constructor when creating this struct, otherwise we do not guarantee the binary compatibility.
+/// </remarks>
 public readonly struct OnCircuitClosedArguments
 {
     /// <summary>

src/Polly.Core/CircuitBreaker/OnCircuitHalfOpenedArguments.cs

@@ -5,6 +5,9 @@ namespace Polly.CircuitBreaker;
 /// <summary>
 /// Arguments used by <see cref="CircuitBreakerStrategyOptions{TResult}.OnHalfOpened"/> event.
 /// </summary>
+/// <remarks>
+/// Always use constructor when creating this struct, otherwise we do not guarantee the binary compatibility.
+/// </remarks>
 public readonly struct OnCircuitHalfOpenedArguments
 {
     /// <summary>

src/Polly.Core/CircuitBreaker/OnCircuitOpenedArguments.cs

@@ -5,6 +5,9 @@ namespace Polly.CircuitBreaker;
 /// <summary>
 /// Arguments used by <see cref="CircuitBreakerStrategyOptions{TResult}.OnOpened"/> event.
 /// </summary>
+/// <remarks>
+/// Always use constructor when creating this struct, otherwise we do not guarantee the binary compatibility.
+/// </remarks>
 public readonly struct OnCircuitOpenedArguments
 {
     /// <summary>

src/Polly.Core/Fallback/OnFallbackArguments.cs

@@ -3,6 +3,9 @@ namespace Polly.Fallback;
 /// <summary>
 /// Represents arguments used in fallback handling scenarios.
 /// </summary>
+/// <remarks>
+/// Always use constructor when creating this struct, otherwise we do not guarantee the binary compatibility.
+/// </remarks>
 public readonly struct OnFallbackArguments
 {
 }

src/Polly.Core/Hedging/OnHedgingArguments.cs

@@ -5,6 +5,9 @@ namespace Polly.Hedging;
 /// <summary>
 /// Represents arguments used by the on-hedging event.
 /// </summary>
+/// <remarks>
+/// Always use constructor when creating this struct, otherwise we do not guarantee the binary compatibility.
+/// </remarks>
 public readonly struct OnHedgingArguments
 {
     /// <summary>

src/Polly.Core/Retry/OnRetryArguments.cs

@@ -5,6 +5,9 @@ namespace Polly.Retry;
 /// <summary>
 /// Represents the arguments used by <see cref="RetryStrategyOptions{TResult}.OnRetry"/> for handling the retry event.
 /// </summary>
+/// <remarks>
+/// Always use constructor when creating this struct, otherwise we do not guarantee the binary compatibility.
+/// </remarks>
 public readonly struct OnRetryArguments
 {
     /// <summary>

src/Polly.Core/Telemetry/ExecutionAttemptArguments.cs

@@ -5,6 +5,9 @@
 /// <summary>
 /// Arguments that encapsulate the execution attempt for retries or hedging.
 /// </summary>
+/// <remarks>
+/// Always use constructor when creating this struct, otherwise we do not guarantee the binary compatibility.
+/// </remarks>
 public readonly struct ExecutionAttemptArguments
 {
     /// <summary>

src/Polly.Core/Telemetry/PipelineExecutedArguments.cs

@@ -5,6 +5,9 @@
 /// <summary>
 /// Arguments that indicate the pipeline execution started.
 /// </summary>
+/// <remarks>
+/// Always use constructor when creating this struct, otherwise we do not guarantee the binary compatibility.
+/// </remarks>
 public readonly struct PipelineExecutedArguments
 {
     /// <summary>

src/Polly.Core/Telemetry/PipelineExecutingArguments.cs

@@ -3,6 +3,9 @@
 /// <summary>
 /// Arguments that indicate the pipeline execution started.
 /// </summary>
+/// <remarks>
+/// Always use constructor when creating this struct, otherwise we do not guarantee the binary compatibility.
+/// </remarks>
 public readonly struct PipelineExecutingArguments
 {
 }

src/Polly.Core/Telemetry/TelemetryEventArguments.cs

@@ -7,6 +7,9 @@
 /// </summary>
 /// <typeparam name="TResult">The type of result.</typeparam>
 /// <typeparam name="TArgs">The arguments associated with the resilience event.</typeparam>
+/// <remarks>
+/// Always use constructor when creating this struct, otherwise we do not guarantee the binary compatibility.
+/// </remarks>
 public readonly struct TelemetryEventArguments<TResult, TArgs>
 {
     /// <summary>