feat: clean-up xml code docs (#198)

arcus-azure · Jun 24, 2021 · 121e5b6 · 121e5b6
1 parent 931143b
commit 121e5b6
Show file tree

Hide file tree

Showing 7 changed files with 87 additions and 80 deletions.
diff --git a/...essaging.Abstractions.ServiceBus/MessageHandling/AzureServiceBusFallbackMessageHandler.cs b/...essaging.Abstractions.ServiceBus/MessageHandling/AzureServiceBusFallbackMessageHandler.cs
@@ -22,23 +22,23 @@ protected AzureServiceBusFallbackMessageHandler(ILogger logger) : base(logger)
         }
 
         /// <summary>
-        ///     Process a new message that was received
+        /// Process a new Azure Service Bus message that was received but couldn't be handled by any of the general registered message handlers.
         /// </summary>
-        /// <param name="message">The Azure Service Bus Message message that was received</param>
-        /// <param name="messageContext">The context providing more information concerning the processing</param>
-        /// <param name="correlationInfo">
-        ///     The information concerning correlation of telemetry and processes by using a variety of unique
-        ///     identifiers.
-        /// </param>
-        /// <param name="cancellationToken">The cancellation token to cancel the processing.</param>
+        /// <param name="message">The Azure Service Bus Message message that was received.</param>
+        /// <param name="messageContext">The context providing more information concerning the processing.</param>
+        /// <param name="correlationInfo">The information concerning correlation of telemetry and processes by using a variety of unique identifiers.</param>
+        /// <param name="cancellationToken">The token to cancel the processing.</param>
+        /// <exception cref="ArgumentNullException">
+        ///     Thrown when the <paramref name="message"/>, the <paramref name="messageContext"/>, or the <paramref name="correlationInfo"/> is <c>null</c>.
+        /// </exception>
         public abstract Task ProcessMessageAsync(
             ServiceBusReceivedMessage message,
             AzureServiceBusMessageContext messageContext,
             MessageCorrelationInfo correlationInfo,
             CancellationToken cancellationToken);
 
         /// <summary>
-        /// Completes the Azure Service Bus message on Azure.
+        /// Completes the Azure Service Bus message on Azure. This will delete the message from the service.
         /// </summary>
         /// <param name="message">The Azure Service Bus message to be completed.</param>
         /// <exception cref="ArgumentNullException">Thrown when the <paramref name="message"/> is <c>null</c>.</exception>
@@ -59,7 +59,8 @@ protected async Task CompleteMessageAsync(ServiceBusReceivedMessage message)
         }
 
         /// <summary>
-        /// Dead letters the Azure Service Bus <paramref name="message"/> on Azure while providing <paramref name="newMessageProperties"/> for properties that has to be modified in the process.
+        /// Dead letters the Azure Service Bus <paramref name="message"/> on Azure
+        /// while providing <paramref name="newMessageProperties"/> for properties that has to be modified in the process.
         /// </summary>
         /// <param name="message">The message that has to be dead lettered.</param>
         /// <param name="newMessageProperties">The properties to modify on the message during the dead lettering of the message.</param>
@@ -106,7 +107,13 @@ protected async Task DeadLetterMessageAsync(ServiceBusReceivedMessage message, s
         }
 
         /// <summary>
-        /// Abandon the Azure Service Bus <paramref name="message"/> on Azure while providing <paramref name="newMessageProperties"/> for properties that has to be modified in the process.
+        /// <para>
+        ///     Abandon the Azure Service Bus <paramref name="message"/> on Azure
+        ///     while providing <paramref name="newMessageProperties"/> for properties that has to be modified in the process.
+        /// </para>
+        /// <para>
+        ///     This will make the message available again for immediate processing as the lock of the message will be released.
+        /// </para>
         /// </summary>
         /// <param name="message">The message that has to be abandoned.</param>
         /// <param name="newMessageProperties">The properties to modify on the message during the abandoning of the message.</param>

diff --git a/src/Arcus.Messaging.Abstractions.ServiceBus/MessageHandling/AzureServiceBusMessageHandler.cs b/src/Arcus.Messaging.Abstractions.ServiceBus/MessageHandling/AzureServiceBusMessageHandler.cs
@@ -18,23 +18,23 @@ public abstract class AzureServiceBusMessageHandler<TMessage> : AzureServiceBusM
         protected AzureServiceBusMessageHandler(ILogger logger) : base(logger) { }
 
         /// <summary>
-        ///     Process a new message that was received
+        /// Process a new Azure Service Bus message that was received.
         /// </summary>
-        /// <param name="message">Message that was received</param>
-        /// <param name="messageContext">Context providing more information concerning the processing</param>
-        /// <param name="correlationInfo">
-        ///     Information concerning correlation of telemetry and processes by using a variety of unique
-        ///     identifiers
-        /// </param>
-        /// <param name="cancellationToken">Cancellation token</param>
+        /// <param name="message">The Azure Service Bus Message message that was received.</param>
+        /// <param name="messageContext">The context providing more information concerning the processing.</param>
+        /// <param name="correlationInfo">The information concerning correlation of telemetry and processes by using a variety of unique identifiers.</param>
+        /// <param name="cancellationToken">The token to cancel the processing.</param>
+        /// <exception cref="ArgumentNullException">
+        ///     Thrown when the <paramref name="message"/>, the <paramref name="messageContext"/>, or the <paramref name="correlationInfo"/> is <c>null</c>.
+        /// </exception>
         public abstract Task ProcessMessageAsync(
             TMessage message,
             AzureServiceBusMessageContext messageContext,
             MessageCorrelationInfo correlationInfo,
             CancellationToken cancellationToken);
 
         /// <summary>
-        /// Completes the Azure Service Bus message on Azure.
+        /// Completes the Azure Service Bus message on Azure. This will delete the message from the service.
         /// </summary>
         /// <exception cref="InvalidOperationException">Thrown when the message handler was not initialized yet.</exception>
         protected async Task CompleteMessageAsync()
@@ -92,7 +92,12 @@ protected async Task DeadLetterMessageAsync(string deadLetterReason, string dead
         }
 
         /// <summary>
-        /// Abandon the Azure Service Bus message on Azure while providing <paramref name="newMessageProperties"/> for properties that has to be modified in the process.
+        /// <para>
+        ///     Abandon the Azure Service Bus message on Azure while providing <paramref name="newMessageProperties"/> for properties that has to be modified in the process.
+        /// </para>
+        /// <para>
+        ///     This will make the message available again for immediate processing as the lock of the message will be released.
+        /// </para>
         /// </summary>
         /// <param name="newMessageProperties">The properties to modify on the message during the abandoning of the message.</param>
         /// <exception cref="InvalidOperationException">Thrown when the message handler was not initialized yet.</exception>

diff --git a/src/Arcus.Messaging.Abstractions.ServiceBus/MessageHandling/AzureServiceBusMessageRouter.cs b/src/Arcus.Messaging.Abstractions.ServiceBus/MessageHandling/AzureServiceBusMessageRouter.cs
@@ -22,7 +22,7 @@ public class AzureServiceBusMessageRouter : MessageRouter, IAzureServiceBusMessa
         /// <summary>
         /// Initializes a new instance of the <see cref="AzureServiceBusMessageRouter"/> class.
         /// </summary>
-        /// <param name="serviceProvider">The service provider instance to retrieve all the <see cref="IMessageHandler{TMessage,TMessageContext}"/> instances.</param>
+        /// <param name="serviceProvider">The service provider instance to retrieve all the <see cref="IAzureServiceBusMessageHandler{TMessage}"/> instances.</param>
         /// <param name="options">The consumer-configurable options to change the behavior of the router.</param>
         /// <param name="logger">The logger instance to write diagnostic trace messages during the routing of the message.</param>
         /// <exception cref="ArgumentNullException">Thrown when the <paramref name="serviceProvider"/> is <c>null</c>.</exception>
@@ -35,7 +35,7 @@ public AzureServiceBusMessageRouter(IServiceProvider serviceProvider, AzureServi
         /// <summary>
         /// Initializes a new instance of the <see cref="AzureServiceBusMessageRouter"/> class.
         /// </summary>
-        /// <param name="serviceProvider">The service provider instance to retrieve all the <see cref="IMessageHandler{TMessage,TMessageContext}"/> instances.</param>
+        /// <param name="serviceProvider">The service provider instance to retrieve all the <see cref="IAzureServiceBusMessageHandler{TMessage}"/> instances.</param>
         /// <param name="options">The consumer-configurable options to change the behavior of the router.</param>
         /// <exception cref="ArgumentNullException">Thrown when the <paramref name="serviceProvider"/> is <c>null</c>.</exception>
         public AzureServiceBusMessageRouter(IServiceProvider serviceProvider, AzureServiceBusMessageRouterOptions options)
@@ -47,7 +47,7 @@ public AzureServiceBusMessageRouter(IServiceProvider serviceProvider, AzureServi
         /// <summary>
         /// Initializes a new instance of the <see cref="AzureServiceBusMessageRouter"/> class.
         /// </summary>
-        /// <param name="serviceProvider">The service provider instance to retrieve all the <see cref="IMessageHandler{TMessage,TMessageContext}"/> instances.</param>
+        /// <param name="serviceProvider">The service provider instance to retrieve all the <see cref="IAzureServiceBusMessageHandler{TMessage}"/> instances.</param>
         /// <param name="logger">The logger instance to write diagnostic trace messages during the routing of the message.</param>
         /// <exception cref="ArgumentNullException">Thrown when the <paramref name="serviceProvider"/> is <c>null</c>.</exception>
         public AzureServiceBusMessageRouter(IServiceProvider serviceProvider, ILogger<AzureServiceBusMessageRouter> logger)
@@ -59,7 +59,7 @@ public AzureServiceBusMessageRouter(IServiceProvider serviceProvider, ILogger<Az
         /// <summary>
         /// Initializes a new instance of the <see cref="AzureServiceBusMessageRouter"/> class.
         /// </summary>
-        /// <param name="serviceProvider">The service provider instance to retrieve all the <see cref="IMessageHandler{TMessage,TMessageContext}"/> instances.</param>
+        /// <param name="serviceProvider">The service provider instance to retrieve all the <see cref="IAzureServiceBusMessageHandler{TMessage}"/> instances.</param>
         /// <exception cref="ArgumentNullException">Thrown when the <paramref name="serviceProvider"/> is <c>null</c>.</exception>
         public AzureServiceBusMessageRouter(IServiceProvider serviceProvider)
             : this(serviceProvider, new AzureServiceBusMessageRouterOptions(), NullLogger.Instance)
@@ -70,7 +70,7 @@ public AzureServiceBusMessageRouter(IServiceProvider serviceProvider)
         /// <summary>
         /// Initializes a new instance of the <see cref="AzureServiceBusMessageRouter"/> class.
         /// </summary>
-        /// <param name="serviceProvider">The service provider instance to retrieve all the <see cref="IMessageHandler{TMessage,TMessageContext}"/> instances.</param>
+        /// <param name="serviceProvider">The service provider instance to retrieve all the <see cref="IAzureServiceBusMessageHandler{TMessage}"/> instances.</param>
         /// <param name="logger">The logger instance to write diagnostic trace messages during the routing of the message.</param>
         /// <exception cref="ArgumentNullException">Thrown when the <paramref name="serviceProvider"/> is <c>null</c>.</exception>
         protected AzureServiceBusMessageRouter(IServiceProvider serviceProvider, ILogger logger)
@@ -82,7 +82,7 @@ protected AzureServiceBusMessageRouter(IServiceProvider serviceProvider, ILogger
         /// <summary>
         /// Initializes a new instance of the <see cref="AzureServiceBusMessageRouter"/> class.
         /// </summary>
-        /// <param name="serviceProvider">The service provider instance to retrieve all the <see cref="IMessageHandler{TMessage,TMessageContext}"/> instances.</param>
+        /// <param name="serviceProvider">The service provider instance to retrieve all the <see cref="IAzureServiceBusMessageHandler{TMessage}"/> instances.</param>
         /// <param name="options">The consumer-configurable options to change the behavior of the router.</param>
         /// <param name="logger">The logger instance to write diagnostic trace messages during the routing of the message.</param>
         /// <exception cref="ArgumentNullException">Thrown when the <paramref name="serviceProvider"/> is <c>null</c>.</exception>
@@ -108,15 +108,17 @@ protected AzureServiceBusMessageRouter(IServiceProvider serviceProvider, AzureSe
 
         /// <summary>
         /// Handle a new <paramref name="message"/> that was received by routing them through registered <see cref="IAzureServiceBusMessageHandler{TMessage}"/>s
-        /// and optionally through an registered <see cref="IFallbackMessageHandler"/> or <see cref="IAzureServiceBusFallbackMessageHandler"/> if none of the message handlers were able to process the <paramref name="message"/>.
+        /// and optionally through an registered <see cref="IFallbackMessageHandler"/> or <see cref="IAzureServiceBusFallbackMessageHandler"/>
+        /// if none of the message handlers were able to process the <paramref name="message"/>.
         /// </summary>
-        /// <param name="message">The message that was received.</param>
+        /// <param name="message">The incoming message that needs to be routed through registered message handlers.</param>
         /// <param name="messageContext">The context in which the <paramref name="message"/> should be processed.</param>
         /// <param name="correlationInfo">The information concerning correlation of telemetry and processes by using a variety of unique identifiers.</param>
         /// <param name="cancellationToken">The token to cancel the message processing.</param>
         /// <remarks>
-        ///     Note that registered <see cref="IAzureServiceBusMessageHandler{TMessage}"/>s with specific Azure Service Bus operations, will not be able to call those operations
-        ///     without an <see cref="ServiceBusReceiver"/>. Use the <see cref="RouteMessageAsync(ServiceBusReceiver,ServiceBusReceivedMessage,AzureServiceBusMessageContext,MessageCorrelationInfo,CancellationToken)"/> instead.
+        ///     Note that registered <see cref="IAzureServiceBusMessageHandler{TMessage}"/>s with specific Azure Service Bus operations (dead-letter, complete...),
+        ///     will not be able to call those operations without an <see cref="ServiceBusReceiver"/>.
+        ///     Use the <see cref="RouteMessageAsync(ServiceBusReceiver,ServiceBusReceivedMessage,AzureServiceBusMessageContext,MessageCorrelationInfo,CancellationToken)"/> instead.
         /// </remarks>
         /// <exception cref="ArgumentNullException">
         ///     Thrown when the <paramref name="message"/>, <paramref name="messageContext"/>, or <paramref name="correlationInfo"/> is <c>null</c>.
@@ -142,12 +144,14 @@ await RouteMessageWithPotentialFallbackAsync(
 
         /// <summary>
         /// Handle a new <paramref name="message"/> that was received by routing them through registered <see cref="IAzureServiceBusMessageHandler{TMessage}"/>s
-        /// and optionally through an registered <see cref="IFallbackMessageHandler"/> or <see cref="IAzureServiceBusFallbackMessageHandler"/> if none of the message handlers were able to process the <paramref name="message"/>.
+        /// and optionally through an registered <see cref="IFallbackMessageHandler"/> or <see cref="IAzureServiceBusFallbackMessageHandler"/>
+        /// if none of the message handlers were able to process the <paramref name="message"/>.
         /// </summary>
         /// <param name="messageReceiver">
-        ///     The instance that can receive Azure Service Bus <see cref="ServiceBusReceivedMessage"/>; used within <see cref="IMessageHandler{TMessage,TMessageContext}"/>s with Azure Service Bus specific operations.
+        ///     The receiver that can call operations (dead letter, complete...) on an Azure Service Bus <see cref="ServiceBusReceivedMessage"/>;
+        ///     used within <see cref="AzureServiceBusMessageHandler{TMessage}"/>s or <see cref="AzureServiceBusFallbackMessageHandler"/>s.
         /// </param>
-        /// <param name="message">The message that was received by the <paramref name="messageReceiver"/>.</param>
+        /// <param name="message">The incoming message that needs to be routed through registered message handlers.</param>
         /// <param name="messageContext">The context in which the <paramref name="message"/> should be processed.</param>
         /// <param name="correlationInfo">The information concerning correlation of telemetry and processes by using a variety of unique identifiers.</param>
         /// <param name="cancellationToken">The token to cancel the message processing.</param>
@@ -172,12 +176,14 @@ public async Task RouteMessageAsync(
 
         /// <summary>
         /// Handle a new <paramref name="message"/> that was received by routing them through registered <see cref="IAzureServiceBusMessageHandler{TMessage}"/>s
-        /// and optionally through an registered <see cref="IFallbackMessageHandler"/> or <see cref="IAzureServiceBusFallbackMessageHandler"/> if none of the message handlers were able to process the <paramref name="message"/>.
+        /// and optionally through an registered <see cref="IFallbackMessageHandler"/> or <see cref="IAzureServiceBusFallbackMessageHandler"/>
+        /// if none of the message handlers were able to process the <paramref name="message"/>.
         /// </summary>
         /// <param name="messageReceiver">
-        ///     The instance that can receive Azure Service Bus <see cref="ServiceBusReceivedMessage"/>; used within <see cref="IMessageHandler{TMessage,TMessageContext}"/>s with Azure Service Bus specific operations.
+        ///     The receiver that can call operations (dead letter, complete...) on an Azure Service Bus <see cref="ServiceBusReceivedMessage"/>;
+        ///     used within <see cref="AzureServiceBusMessageHandler{TMessage}"/>s or <see cref="AzureServiceBusFallbackMessageHandler"/>s.
         /// </param>
-        /// <param name="message">The message that was received by the <paramref name="messageReceiver"/>.</param>
+        /// <param name="message">The incoming message that needs to be routed through registered message handlers.</param>
         /// <param name="messageContext">The context in which the <paramref name="message"/> should be processed.</param>
         /// <param name="correlationInfo">The information concerning correlation of telemetry and processes by using a variety of unique identifiers.</param>
         /// <param name="cancellationToken">The token to cancel the message processing.</param>