Add XML doc to IConsumer and related entities.

lukebakken · lukebakken · commit 670aac49ee3c · 2025-03-20T15:30:17.000-07:00
Follow-up to #105.
diff --git a/RabbitMQ.AMQP.Client/ConsumerException.cs b/RabbitMQ.AMQP.Client/ConsumerException.cs
@@ -0,0 +1,18 @@
+// This source code is dual-licensed under the Apache License, version 2.0,
+// and the Mozilla Public License, version 2.0.
+// Copyright (c) 2017-2024 Broadcom. All Rights Reserved. The term "Broadcom" refers to Broadcom Inc. and/or its subsidiaries.
+
+using System;
+
+namespace RabbitMQ.AMQP.Client
+{
+    /// <summary>
+    /// Exception returned during consumer operations. See <see cref="IConsumer"/>.
+    /// </summary>
+    public class ConsumerException : Exception
+    {
+        public ConsumerException(string message) : base(message)
+        {
+        }
+    }
+}
diff --git a/RabbitMQ.AMQP.Client/IConsumer.cs b/RabbitMQ.AMQP.Client/IConsumer.cs
@@ -2,61 +2,82 @@
 // and the Mozilla Public License, version 2.0.
 // Copyright (c) 2017-2024 Broadcom. All Rights Reserved. The term "Broadcom" refers to Broadcom Inc. and/or its subsidiaries.
 
-using System;
 using System.Collections.Generic;
 using System.Threading.Tasks;
 
 namespace RabbitMQ.AMQP.Client
 {
-    public class ConsumerException : Exception
-    {
-        public ConsumerException(string message) : base(message)
-        {
-        }
-    }
-
     // TODO cancellation token
+    /// <summary>
+    /// Delegate to process an incoming message.
+    /// </summary>
+    /// <param name="context">The message context.</param>
+    /// <param name="message">The message itself.</param>
+    /// <returns><see cref="Task"/> that represents the async operation.</returns>
     public delegate Task MessageHandler(IContext context, IMessage message);
 
+    /// <summary>
+    /// <para>API to consume messages from a RabbitMQ queue.</para>
+    /// <para>Instances are configured and created with a <see cref="IConsumerBuilder"/>.</para>
+    /// <para>See <see cref="IConnection.ConsumerBuilder()"/> and <see cref="IConsumerBuilder"/>.</para>
+    /// </summary>
     public interface IConsumer : ILifeCycle
     {
+        /// <summary>
+        /// Pause the consumer to stop receiving messages.
+        /// </summary>
         void Pause();
+
+        /// <summary>
+        /// Request to receive messages again.
+        /// </summary>
         void Unpause();
+
+        /// <summary>
+        /// Returns the number of unsettled messages.
+        /// </summary>
         long UnsettledMessageCount { get; }
     }
 
     public interface IContext
     {
-        ///<summary>
-        /// Accept the message (AMQP 1.0 <code>accepted</code> outcome).
-        ///
-        /// This means the message has been processed and the broker can delete it.
-        /// 
+        /// <summary>
+        /// <para>Accept the message (AMQP 1.0 <c>accepted</c> outcome).</para>
+        /// <para>This means the message has been processed and the broker can delete it.</para>
         /// </summary>
         void Accept();
 
         ///<summary>
-        /// Discard the message (AMQP 1.0 <code>rejected</code> outcome).
-        ///This means the message cannot be processed because it is invalid, the broker can drop it
-        /// or dead-letter it if it is configured.
+        /// <para>Discard the message (AMQP 1.0 <c>rejected</c> outcome).</para>
+        /// <para>
+        ///   This means the message cannot be processed because it is invalid, the broker can
+        ///   drop it or dead-letter it if it is configured.
+        /// </para>
         ///</summary>
         void Discard();
 
         ///<summary>
-        ///Discard the message with annotations to combine with the existing message annotations.
-        ///This means the message cannot be processed because it is invalid, the broker can drop it
-        ///or dead-letter it if it is configured.
-        ///Application-specific annotation keys must start with the <code>x-opt-</code> prefix.
-        ///Annotation keys the broker understands starts with <code>x-</code>, but not with <code>x-opt-
-        ///</code>.
-        ///This maps to the AMQP 1.0 <code>
-        ///modified{delivery-failed = true, undeliverable-here = true}</code> outcome.
-        /// <param name="annotations"> annotations message annotations to combine with existing ones </param>
-        ///<a
-        ///    href="https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-modified">AMQP
-        ///    1.0 <code>modified</code> outcome</a>
-        ///
-        /// The annotations can be used only with Quorum queues, see https://www.rabbitmq.com/docs/amqp#modified-outcome
+        /// <para>
+        ///   Discard the message with annotations to combine with the existing message annotations.
+        /// </para>
+        /// <para>
+        ///   This means the message cannot be processed because it is invalid, the broker can drop
+        ///   it or dead-letter it if it is configured.
+        /// </para>
+        /// <para>
+        ///   Application-specific annotation keys must start with the <c>x-opt-</c> prefix.
+        /// </para>
+        /// <para>
+        ///   Annotation keys that the broker understands start with <c>x-</c>, but not with
+        ///   <c>x-opt-</c>. This maps to the AMQP 1.0 <c>modified{delivery-failed = false,
+        ///   undeliverable-here = false}</c> outcome.
+        /// </para>
+        /// <para>
+        ///   The annotations can be used only with Quorum queues, see
+        ///   <a href="https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-modified">
+        ///   AMQP 1.0 <c>modified</c> outcome.</a>
+        /// </para>
+        /// <param name="annotations">Message annotations to combine with existing ones.</param>
         ///</summary>
         void Discard(Dictionary<string, object> annotations);
 
@@ -70,23 +91,27 @@ public interface IContext
         void Requeue();
 
         ///<summary>
-        ///Requeue the message with annotations to combine with the existing message annotations.
-        /// 
-        ///This means the message has not been processed and the broker can requeue it and deliver it
-        /// to the same or a different consumer.
-        /// Application-specific annotation keys must start with the <code>x-opt-</code> prefix.
-        /// Annotation keys the broker understands starts with <code>x-</code>, but not with <code>x-opt-
-        /// </code>.
-        ///
-        /// This maps to the AMQP 1.0 <code>
-        /// modified{delivery-failed = false, undeliverable-here = false}</code> outcome.
-        ///
-        /// <param name="annotations"> annotations message annotations to combine with existing ones </param>
-        ///<a
-        ///     href="https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-modified">AMQP
-        ///     1.0 <code>modified</code> outcome</a>
-        ///
-        ///The annotations can be used only with Quorum queues, see https://www.rabbitmq.com/docs/amqp#modified-outcome
+        /// <para>
+        ///   Requeue the message with annotations to combine with the existing message annotations.
+        /// </para>
+        /// <para>
+        ///   This means the message has not been processed and the broker can requeue it and
+        ///   deliver it to the same or a different consumer.
+        /// </para>
+        /// <para>
+        ///   Application-specific annotation keys must start with the <c>x-opt-</c> prefix.
+        /// </para>
+        /// <para>
+        ///   Annotation keys that the broker understands start with <c>x-</c>, but not with
+        ///   <c>x-opt-</c>. This maps to the AMQP 1.0 <c>modified{delivery-failed = false,
+        ///   undeliverable-here = false}</c> outcome.
+        /// </para>
+        /// <para>
+        ///   The annotations can be used only with Quorum queues, see
+        ///   <a href="https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-modified">
+        ///   AMQP 1.0 <c>modified</c> outcome.</a>
+        /// </para>
+        /// <param name="annotations">Message annotations to combine with existing ones.</param>
         ///</summary>
         void Requeue(Dictionary<string, object> annotations);
     }
diff --git a/RabbitMQ.AMQP.Client/Impl/AmqpConsumer.cs b/RabbitMQ.AMQP.Client/Impl/AmqpConsumer.cs
@@ -193,6 +193,9 @@ await _configuration.Handler(context, amqpMessage)
             Trace.WriteLine(TraceLevel.Verbose, $"{ToString()} is closed.");
         }
 
+        /// <summary>
+        /// Pause the consumer to stop receiving messages.
+        /// </summary>
         public void Pause()
         {
             if (_receiverLink is null)
@@ -224,8 +227,14 @@ ref Unsafe.As<PauseStatus, int>(ref _pauseStatus),
             }
         }
 
+        /// <summary>
+        /// Get the number of unsettled messages.
+        /// </summary>
         public long UnsettledMessageCount => _unsettledMessageCounter.Get();
 
+        /// <summary>
+        /// Request to receive messages again.
+        /// </summary>
         public void Unpause()
         {
             if (_receiverLink is null)
diff --git a/RabbitMQ.AMQP.Client/Impl/DeliveryContext.cs b/RabbitMQ.AMQP.Client/Impl/DeliveryContext.cs
@@ -24,6 +24,10 @@ public DeliveryContext(IReceiverLink link, Message message, UnsettledMessageCoun
             _metricsReporter = metricsReporter;
         }
 
+        /// <summary>
+        /// <para>Accept the message (AMQP 1.0 <c>accepted</c> outcome).</para>
+        /// <para>This means the message has been processed and the broker can delete it.</para>
+        /// </summary>
         public void Accept()
         {
             try
@@ -43,6 +47,13 @@ public void Accept()
             }
         }
 
+        ///<summary>
+        /// <para>Discard the message (AMQP 1.0 <c>rejected</c> outcome).</para>
+        /// <para>
+        ///   This means the message cannot be processed because it is invalid, the broker can
+        ///   drop it or dead-letter it if it is configured.
+        /// </para>
+        ///</summary>
         public void Discard()
         {
             try
diff --git a/Tests/OAuth2Tests.cs b/Tests/OAuth2Tests.cs
@@ -7,11 +7,8 @@
 using System.IdentityModel.Tokens.Jwt;
 using System.Linq;
 using System.Security.Claims;
-using System.Security.Cryptography;
-using System.Text;
 using System.Threading;
 using System.Threading.Tasks;
-using Amqp;
 using Microsoft.IdentityModel.Tokens;
 using RabbitMQ.AMQP.Client;
 using RabbitMQ.AMQP.Client.Impl;
@@ -55,7 +52,7 @@ public async Task RefreshTokenShouldNotDisconnectTheClient()
                     .OAuth2Options(new OAuth2Options(GenerateToken(DateTime.UtcNow.AddMilliseconds(1_000))))
                     .Build());
             await connection.RefreshTokenAsync(GenerateToken(DateTime.UtcNow.AddMinutes(5)));
-            Thread.Sleep(TimeSpan.FromSeconds(1));
+            await Task.Delay(TimeSpan.FromSeconds(1));
             Assert.NotNull(connection);
             Assert.Equal(State.Open, connection.State);
             await connection.CloseAsync();
@@ -131,7 +128,7 @@ public async Task ConnectionShouldReconnectWithTheNewToken()
             };
 
             Assert.Equal(State.Open, connection.State);
-            Thread.Sleep(TimeSpan.FromSeconds(1));
+            await Task.Delay(TimeSpan.FromSeconds(1));
             await WaitUntilConnectionIsKilledAndOpen(_containerId);
             Assert.Equal(State.Open, connection.State);
             await WhenTcsCompletes(twoRecoveryEventsSeenTcs);

Original file line number	Diff line number	Diff line change
`@@ -193,6 +193,9 @@ await _configuration.Handler(context, amqpMessage)`
`193`	`193`	`Trace.WriteLine(TraceLevel.Verbose, $"{ToString()} is closed.");`
`194`	`194`	`}`
`195`	`195`
	`196`	`+ /// <summary>`
	`197`	`+ /// Pause the consumer to stop receiving messages.`
	`198`	`+ /// </summary>`
`196`	`199`	`public void Pause()`
`197`	`200`	`{`
`198`	`201`	`if (_receiverLink is null)`
`@@ -224,8 +227,14 @@ ref Unsafe.As<PauseStatus, int>(ref _pauseStatus),`
`224`	`227`	`}`
`225`	`228`	`}`
`226`	`229`
	`230`	`+ /// <summary>`
	`231`	`+ /// Get the number of unsettled messages.`
	`232`	`+ /// </summary>`
`227`	`233`	`public long UnsettledMessageCount => _unsettledMessageCounter.Get();`
`228`	`234`
	`235`	`+ /// <summary>`
	`236`	`+ /// Request to receive messages again.`
	`237`	`+ /// </summary>`
`229`	`238`	`public void Unpause()`
`230`	`239`	`{`
`231`	`240`	`if (_receiverLink is null)`
Original file line number	Diff line number	Diff line change
`@@ -24,6 +24,10 @@ public DeliveryContext(IReceiverLink link, Message message, UnsettledMessageCoun`
`24`	`24`	`_metricsReporter = metricsReporter;`
`25`	`25`	`}`
`26`	`26`
	`27`	`+ /// <summary>`
	`28`	`+ /// <para>Accept the message (AMQP 1.0 <c>accepted</c> outcome).</para>`
	`29`	`+ /// <para>This means the message has been processed and the broker can delete it.</para>`
	`30`	`+ /// </summary>`
`27`	`31`	`public void Accept()`
`28`	`32`	`{`
`29`	`33`	`try`
`@@ -43,6 +47,13 @@ public void Accept()`
`43`	`47`	`}`
`44`	`48`	`}`
`45`	`49`
	`50`	`+ ///<summary>`
	`51`	`+ /// <para>Discard the message (AMQP 1.0 <c>rejected</c> outcome).</para>`
	`52`	`+ /// <para>`
	`53`	`+ /// This means the message cannot be processed because it is invalid, the broker can`
	`54`	`+ /// drop it or dead-letter it if it is configured.`
	`55`	`+ /// </para>`
	`56`	`+ ///</summary>`
`46`	`57`	`public void Discard()`
`47`	`58`	`{`
`48`	`59`	`try`