Xml doc updates for the rate limiting (#1711)

* Describe the option better

* Describe the rate limiter

---------

Co-authored-by: danielmarbach <[email protected]>

projects/RabbitMQ.Client/CreateChannelOptions.cs

@@ -52,7 +52,10 @@ public sealed class CreateChannelOptions
         /// <summary>
         /// If the publisher confirmation tracking is enabled, this represents the rate limiter used to
         /// throttle additional attempts to publish once the threshold is reached.
+        ///
+        /// Defaults to a <see cref="ThrottlingRateLimiter"/> with a limit of 128 and a throttling percentage of 50% with a delay during throttling.
         /// </summary>
+        /// <remarks>Setting the rate limiter to <c>null</c> disables the rate limiting entirely.</remarks>
         public RateLimiter? OutstandingPublisherConfirmationsRateLimiter { get; set; } = new ThrottlingRateLimiter(128);
 
         /// <summary>

projects/RabbitMQ.Client/ThrottlingRateLimiter.cs

@@ -36,14 +36,34 @@
 
 namespace RabbitMQ.Client
 {
+    /// <summary>
+    /// A rate limiter that controls the rate of operations by limiting concurrency and applying delays 
+    /// when a specified threshold of concurrency usage is reached.
+    ///
+    /// The delay algorithm checks the current available permits from the concurrency limiter. If the available permits are greater than or equal
+    /// to the throttling threshold, no delay is applied.  Otherwise, it calculates a delay based on the percentage of permits used,
+    /// scaling it up to a maximum of 1000 milliseconds.
+    /// </summary>
     public class ThrottlingRateLimiter : RateLimiter
     {
+        /// <summary>
+        /// The default throttling percentage, which defines the threshold for applying throttling, set to 50%.
+        /// </summary>
         public const int DefaultThrottlingPercentage = 50;
 
         private readonly ConcurrencyLimiter _concurrencyLimiter;
         private readonly int _maxConcurrency;
         private readonly int _throttlingThreshold;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ThrottlingRateLimiter"/> class with the specified
+        /// maximum number of concurrent calls and an optional throttling percentage.
+        /// </summary>
+        /// <param name="maxConcurrentCalls">The maximum number of concurrent operations allowed.</param>
+        /// <param name="throttlingPercentage">
+        /// The percentage of <paramref name="maxConcurrentCalls"/> at which throttling is triggered. 
+        /// Defaults to 50% if not specified.
+        /// </param>
         public ThrottlingRateLimiter(int maxConcurrentCalls, int? throttlingPercentage = DefaultThrottlingPercentage)
         {
             _maxConcurrency = maxConcurrentCalls;