[Chore] Clean Up XML Comments for V10 - Core Framework Documentation (BrighterCommand#3646)

* Initial plan

* Improve XML documentation for core value types and enums

Co-authored-by: iancooper <45537+iancooper@users.noreply.github.com>

* Add missing license headers and improve request-reply documentation

Co-authored-by: iancooper <45537+iancooper@users.noreply.github.com>

* Improve documentation for RoutingKey and Subscription classes

Co-authored-by: iancooper <45537+iancooper@users.noreply.github.com>

* Improve ServiceActivator interface documentation and add missing license headers

Co-authored-by: iancooper <45537+iancooper@users.noreply.github.com>

* Complete XML documentation cleanup for core value types and enums

Co-authored-by: iancooper <45537+iancooper@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: iancooper <45537+iancooper@users.noreply.github.com>

Author: Copilot

src/Paramore.Brighter.ServiceActivator/IAmAConsumer.cs

@@ -1,50 +1,89 @@
+#region Licence
+/* The MIT License (MIT)
+Copyright © 2025 Ian Cooper <ian_hammond_cooper@yahoo.co.uk>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE. */
+
+#endregion
+
 using System;
 using System.Threading.Tasks;
 
 namespace Paramore.Brighter.ServiceActivator
 {
+    /// <summary>
+    /// Interface for a consumer that processes messages from a subscription.
+    /// </summary>
+    /// <remarks>
+    /// Consumers represent individual worker instances that process messages from channels.
+    /// They are managed by the dispatcher and can be started, stopped, and monitored.
+    /// </remarks>
     public interface IAmAConsumer : IDisposable
     {
         /// <summary>
-        /// Gets or sets the name.
+        /// Gets the name of this consumer.
         /// </summary>
-        /// <value>The name.</value>
+        /// <value>The <see cref="ConsumerName"/> identifying this consumer.</value>
         ConsumerName Name { get; }
 
         /// <summary>
-        /// What is the subscription that this Consumer is for
+        /// Gets or sets the subscription that this Consumer is processing.
         /// </summary>
+        /// <value>The <see cref="Subscription"/> being processed by this consumer.</value>
         Subscription Subscription { get; set; }
 
         /// <summary>
-        /// Gets the performer.
+        /// Gets the performer that executes the message processing logic.
         /// </summary>
-        /// <value>The performer.</value>
+        /// <value>The <see cref="IAmAPerformer"/> responsible for message processing.</value>
         IAmAPerformer Performer { get; }
 
         /// <summary>
-        /// Gets or sets the state.
+        /// Gets or sets the current state of the consumer.
         /// </summary>
-        /// <value>The state.</value>
+        /// <value>The <see cref="ConsumerState"/> indicating the current operational state.</value>
         ConsumerState State { get; set; }
 
         /// <summary>
-        /// Gets or sets the job.
+        /// Gets or sets the background task running the consumer.
         /// </summary>
-        /// <value>The job.</value>
+        /// <value>The <see cref="Task"/> representing the consumer's background work, or null if not running.</value>
         Task? Job { get; set; }
 
+        /// <summary>
+        /// Gets or sets the identifier for the background job.
+        /// </summary>
+        /// <value>The <see cref="int"/> job identifier.</value>
         int JobId { get; set; }
 
         /// <summary>
-        /// Opens the task queue and begin receiving messages.
+        /// Opens the task queue and begins receiving messages.
         /// </summary>
+        /// <remarks>
+        /// This starts the consumer's background processing and begins consuming messages from the subscription.
+        /// </remarks>
         void Open();
 
         /// <summary>
-        /// Shuts the task, which will not receive messages.
+        /// Shuts down the task, which will stop receiving messages.
         /// </summary>
-        /// <param name="subscriptionRoutingKey"></param>
+        /// <param name="subscriptionRoutingKey">The <see cref="RoutingKey"/> of the subscription to shut down.</param>
         void Shut(RoutingKey subscriptionRoutingKey);
     }
 }

src/Paramore.Brighter.ServiceActivator/IAmAMessagePump.cs

@@ -30,25 +30,33 @@ namespace Paramore.Brighter.ServiceActivator
     /// <summary>
     /// Interface IAmAMessagePump
     /// The message pump reads <see cref="Message"/>s from a channel, translates them into a <see cref="Request"/>s and asks <see cref="CommandProcessor"/> to
-    /// dispatch them to an <see cref="IHandleRequests"/>. It is classical message loop, and so should run until it receives an <see cref="MessageType.MT_QUIT"/>
+    /// dispatch them to an <see cref="IHandleRequests"/>. It is a classical message loop, and so should run until it receives an <see cref="MessageType.MT_QUIT"/>
     /// message. Clients of the message pump need to add a <see cref="Message"/> with of type <see cref="MessageType.MT_QUIT"/> to the <see cref="Channel"/> to abort
     /// a loop once started. The <see cref="IAmAChannelSync"/> interface provides a <see cref="IAmAChannelSync.Stop"/> method for this.
     /// </summary>
+    /// <remarks>
+    /// Message pumps implement the Service Activator pattern and are responsible for the continuous processing
+    /// of messages from messaging infrastructure like queues or streams.
+    /// </remarks>
     public interface IAmAMessagePump
     {
         /// <summary>
-        /// The <see cref="MessagePumpType"/> of this message pump; indicates Reactor or Proactor
+        /// Gets the <see cref="MessagePumpType"/> of this message pump; indicates Reactor or Proactor.
         /// </summary>
+        /// <value>A <see cref="MessagePumpType"/> indicating the type of message processing pattern used.</value>
         MessagePumpType MessagePumpType { get; }
 
         /// <summary>
         /// Runs the message pump, performing the following:
         /// - Gets a message from a queue/stream
         /// - Translates the message to the local type system
         /// - Dispatches the message to waiting handlers
-        /// - Handles any exceptions that occur during the dispatch and tries to keep the pump alive  
+        /// - Handles any exceptions that occur during the dispatch and tries to keep the pump alive
         /// </summary>
-        /// <exception cref="Exception"></exception>
+        /// <exception cref="Exception">Thrown when an unrecoverable error occurs during message processing.</exception>
+        /// <remarks>
+        /// This method will block and run continuously until a quit message is received or an unrecoverable error occurs.
+        /// </remarks>
         void Run();
     }
 }

src/Paramore.Brighter.ServiceActivator/IDispatcher.cs

@@ -32,64 +32,76 @@ namespace Paramore.Brighter.ServiceActivator
     /// Interface IDispatcher
     /// The 'core' Service Activator class, the Dispatcher controls and co-ordinates the creation of readers from channels, and dispatching the commands and
     /// events translated from those messages to handlers. It controls the lifetime of the application through <see cref="Receive"/> and <see cref="End"/> and allows
-    /// the stop and start of individual connections through <see cref="Open"/> and <see cref="Shut"/>
+    /// the stop and start of individual connections through <see cref="Open"/> and <see cref="Shut"/>.
     /// </summary>
+    /// <remarks>
+    /// The Dispatcher implements the Service Activator pattern and coordinates multiple message pumps
+    /// to process messages from different channels concurrently.
+    /// </remarks>
     public interface IDispatcher
     {
         /// <summary>
-        /// Gets the <see cref="Consumer"/>s
+        /// Gets the <see cref="Consumer"/>s managed by this dispatcher.
         /// </summary>
-        /// <value>The consumers.</value>
+        /// <value>An <see cref="IEnumerable{T}"/> of <see cref="IAmAConsumer"/> instances.</value>
         IEnumerable<IAmAConsumer> Consumers { get; }
 
         /// <summary>
         /// Gets or sets the name for this dispatcher instance.
-        /// Used when communicating with this instance via the Control Bus
+        /// Used when communicating with this instance via the Control Bus.
         /// </summary>
-        /// <value>The name of the host.</value>
+        /// <value>The <see cref="HostName"/> of the dispatcher instance.</value>
         HostName HostName { get; set; }
 
         /// <summary>
-        /// Ends this instance.
+        /// Ends this dispatcher instance, stopping all message processing.
         /// </summary>
-        /// <returns>Task.</returns>
+        /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
         Task End();
 
         /// <summary>
-        /// Opens the specified subscription.
+        /// Opens the specified subscription for message processing.
         /// </summary>
-        /// <param name="subscription">The subscription.</param>
+        /// <param name="subscription">The <see cref="Subscription"/> to open.</param>
         void Open(Subscription subscription);
 
         /// <summary>
-        /// Opens the specified subscription name.
+        /// Opens the specified subscription by name for message processing.
         /// </summary>
-        /// <param name="subscriptionName"></param>
+        /// <param name="subscriptionName">The <see cref="SubscriptionName"/> of the subscription to open.</param>
         void Open(SubscriptionName subscriptionName);
 
         /// <summary>
         /// Begins listening for messages on channels, and dispatching them to request handlers.
         /// </summary>
+        /// <remarks>
+        /// This method will typically block and run continuously until <see cref="End"/> is called.
+        /// </remarks>
         void Receive();
 
         /// <summary>
-        /// Shuts the specified subscription.
+        /// Shuts down the specified subscription, stopping message processing for that subscription.
         /// </summary>
-        /// <param name="subscription">The subscription.</param>
+        /// <param name="subscription">The <see cref="Subscription"/> to shut down.</param>
         void Shut(Subscription subscription);
 
         /// <summary>
-        /// Shuts the specified subscription name.
+        /// Shuts down the specified subscription by name, stopping message processing for that subscription.
         /// </summary>
-        /// <param name="subscriptionName">Name of the subscription.</param>
+        /// <param name="subscriptionName">The <see cref="SubscriptionName"/> of the subscription to shut down.</param>
         void Shut(SubscriptionName subscriptionName);
 
         /// <summary>
-        /// Get the current running state of the dispatcher
+        /// Gets the current running state of the dispatcher.
         /// </summary>
-        /// <returns>Array of all available subscriptions and how many are currency running</returns>
+        /// <returns>An array of <see cref="DispatcherStateItem"/> showing all available subscriptions and how many are currently running.</returns>
         DispatcherStateItem[] GetState();
 
+        /// <summary>
+        /// Sets the number of active performers for a specific connection.
+        /// </summary>
+        /// <param name="connectionName">The <see cref="string"/> name of the connection.</param>
+        /// <param name="numberOfPerformers">The <see cref="int"/> number of performers to set.</param>
         void SetActivePerformers(string connectionName, int numberOfPerformers);
     }
 }

src/Paramore.Brighter/ChannelName.cs

@@ -25,16 +25,20 @@ THE SOFTWARE. */
 namespace Paramore.Brighter
 {
     /// <summary>
-    /// The name of a channel used to wrap communication with a Broker
+    /// The name of a channel used to wrap communication with a Broker.
     /// </summary>
+    /// <remarks>
+    /// Channel names typically represent queue names or other addressing mechanisms 
+    /// used by messaging infrastructure to route messages.
+    /// </remarks>
     public class ChannelName
     {
         private readonly string _name;
 
         /// <summary>
         /// Initializes a new instance of the <see cref="ChannelName"/> class.
         /// </summary>
-        /// <param name="name">The name.</param>
+        /// <param name="name">The <see cref="string"/> name of the channel.</param>
         public ChannelName(string name)
         {
             _name = name;
@@ -43,46 +47,46 @@ public ChannelName(string name)
         /// <summary>
         /// Gets the name of the channel as a string.
         /// </summary>
-        /// <value>The value.</value>
+        /// <value>The <see cref="string"/> value of the channel name.</value>
         public string Value
         {
             get { return _name; }
         }
 
         /// <summary>
-        /// Returns a <see cref="System.String" /> that represents this instance.
+        /// Returns a <see cref="string" /> that represents this instance.
         /// </summary>
-        /// <returns>A <see cref="System.String" /> that represents this instance.</returns>
+        /// <returns>A <see cref="string" /> containing the channel name.</returns>
         public override string ToString()
         {
             return _name;
         }
 
         /// <summary>
-        /// Performs an implicit conversion from <see cref="ChannelName"/> to <see cref="System.String"/>.
+        /// Performs an implicit conversion from <see cref="ChannelName"/> to <see cref="string"/>.
         /// </summary>
-        /// <param name="rhs">The RHS.</param>
-        /// <returns>The result of the conversion.</returns>
+        /// <param name="rhs">The <see cref="ChannelName"/> to convert.</param>
+        /// <returns>The <see cref="string"/> result of the conversion.</returns>
         public static implicit operator string?(ChannelName rhs)
         {
             return rhs?.ToString();
         }
 
         /// <summary>
-        /// Performs an implicit conversion from <see cref="System.String"/> to <see cref="ChannelName"/>.
+        /// Performs an implicit conversion from <see cref="string"/> to <see cref="ChannelName"/>.
         /// </summary>
-        /// <param name="rhs">The RHS.</param>
-        /// <returns>The result of the conversion.</returns>
+        /// <param name="rhs">The <see cref="string"/> to convert.</param>
+        /// <returns>The <see cref="ChannelName"/> result of the conversion.</returns>
         public static implicit operator ChannelName(string rhs)
         {
             return new ChannelName(rhs);
         }
 
         /// <summary>
-        /// Do the channel name's match?
+        /// Determines whether the channel names match.
         /// </summary>
-        /// <param name="other">The other.</param>
-        /// <returns><c>true</c> if XXXX, <c>false</c> otherwise.</returns>
+        /// <param name="other">The other <see cref="ChannelName"/> to compare.</param>
+        /// <returns><c>true</c> if the channel names are equal; otherwise, <c>false</c>.</returns>
         public bool Equals(ChannelName other)
         {
             if (ReferenceEquals(null, other)) return false;
@@ -91,10 +95,10 @@ public bool Equals(ChannelName other)
         }
 
         /// <summary>
-        /// Do the channel name's match?
+        /// Determines whether the channel names match.
         /// </summary>
-        /// <param name="obj">The object to compare with the current object.</param>
-        /// <returns><c>true</c> if the specified <see cref="System.Object" /> is equal to this instance; otherwise, <c>false</c>.</returns>
+        /// <param name="obj">The <see cref="object"/> to compare with the current object.</param>
+        /// <returns><c>true</c> if the specified <see cref="object" /> is equal to this instance; otherwise, <c>false</c>.</returns>
         public override bool Equals(object? obj)
         {
             if (ReferenceEquals(null, obj)) return false;
@@ -113,27 +117,32 @@ public override int GetHashCode()
         }
 
         /// <summary>
-        /// Implements the ==. Do the channel name's match?
+        /// Implements the == operator. Determines whether the channel names match.
         /// </summary>
-        /// <param name="left">The left.</param>
-        /// <param name="right">The right.</param>
-        /// <returns>The result of the operator.</returns>
+        /// <param name="left">The left <see cref="ChannelName"/>.</param>
+        /// <param name="right">The right <see cref="ChannelName"/>.</param>
+        /// <returns><c>true</c> if the channel names are equal; otherwise, <c>false</c>.</returns>
         public static bool operator ==(ChannelName left, ChannelName right)
         {
             return Equals(left, right);
         }
 
         /// <summary>
-        /// Implements the !=. Do the channel name's not match?
+        /// Implements the != operator. Determines whether the channel names do not match.
         /// </summary>
-        /// <param name="left">The left.</param>
-        /// <param name="right">The right.</param>
-        /// <returns>The result of the operator.</returns>
+        /// <param name="left">The left <see cref="ChannelName"/>.</param>
+        /// <param name="right">The right <see cref="ChannelName"/>.</param>
+        /// <returns><c>true</c> if the channel names are not equal; otherwise, <c>false</c>.</returns>
         public static bool operator !=(ChannelName left, ChannelName right)
         {
             return !Equals(left, right);
         }
 
+        /// <summary>
+        /// Determines whether the specified channel name is null or empty.
+        /// </summary>
+        /// <param name="channelName">The <see cref="ChannelName"/> to test.</param>
+        /// <returns><c>true</c> if the channel name is null or empty; otherwise, <c>false</c>.</returns>
         public static bool IsNullOrEmpty(ChannelName? channelName)
         {
             return channelName is not null && string.IsNullOrEmpty(channelName._name);