Add XML docs and cleanup to mediator core interfaces/classes

Vadim Belov · Vadim Belov · commit e54e049664f9 · 2026-01-21T10:33:57.000-08:00
Extensive XML documentation was added to all major mediator interfaces and classes, improving code readability and IDE support. Updated using directives for EasyExtensions.Mediator.Contracts across files. Replaced static lambdas in ConcurrentDictionary.GetOrAdd with non-static versions for compatibility. Removed TypeForwardings.cs and related type forwarding attributes. Made minor code style improvements and clarified dependencies. No functional changes to mediator logic.
diff --git a/Sources/EasyExtensions.Mediator/IMediator.cs b/Sources/EasyExtensions.Mediator/IMediator.cs
@@ -3,7 +3,5 @@ namespace EasyExtensions.Mediator
     /// <summary>
     /// Defines a mediator to encapsulate request/response and publishing interaction patterns
     /// </summary>
-    public interface IMediator : ISender, IPublisher
-    {
-    }
+    public interface IMediator : ISender, IPublisher { }
 }
diff --git a/Sources/EasyExtensions.Mediator/INotificationHandler.cs b/Sources/EasyExtensions.Mediator/INotificationHandler.cs
@@ -1,3 +1,4 @@
+using EasyExtensions.Mediator.Contracts;
 using System.Threading;
 using System.Threading.Tasks;
 
diff --git a/Sources/EasyExtensions.Mediator/INotificationPublisher.cs b/Sources/EasyExtensions.Mediator/INotificationPublisher.cs
@@ -5,8 +5,21 @@
 
 namespace EasyExtensions.Mediator
 {
+    /// <summary>
+    /// Defines a contract for publishing notifications to one or more notification handler executors asynchronously.
+    /// </summary>
+    /// <remarks>Implementations of this interface are responsible for invoking the provided notification
+    /// handler executors with the specified notification. The publishing process is typically asynchronous and may
+    /// involve invoking handlers in parallel or sequentially, depending on the implementation.</remarks>
     public interface INotificationPublisher
     {
+        /// <summary>
+        /// Publishes a notification to the specified handler executors asynchronously.
+        /// </summary>
+        /// <param name="handlerExecutors">A collection of handler executors that will process the notification. Cannot be null.</param>
+        /// <param name="notification">The notification instance to be published. Cannot be null.</param>
+        /// <param name="cancellationToken">A token that can be used to cancel the publish operation.</param>
+        /// <returns>A task that represents the asynchronous publish operation.</returns>
         Task Publish(IEnumerable<NotificationHandlerExecutor> handlerExecutors, INotification notification,
             CancellationToken cancellationToken);
     }
diff --git a/Sources/EasyExtensions.Mediator/IPublisher.cs b/Sources/EasyExtensions.Mediator/IPublisher.cs
@@ -1,4 +1,5 @@
-﻿using System.Threading;
+﻿using EasyExtensions.Mediator.Contracts;
+using System.Threading;
 using System.Threading.Tasks;
 
 namespace EasyExtensions.Mediator
diff --git a/Sources/EasyExtensions.Mediator/IRequestHandler.cs b/Sources/EasyExtensions.Mediator/IRequestHandler.cs
@@ -1,3 +1,4 @@
+using EasyExtensions.Mediator.Contracts;
 using System.Threading;
 using System.Threading.Tasks;
 
diff --git a/Sources/EasyExtensions.Mediator/ISender.cs b/Sources/EasyExtensions.Mediator/ISender.cs
@@ -1,4 +1,5 @@
-﻿using System.Collections.Generic;
+﻿using EasyExtensions.Mediator.Contracts;
+using System.Collections.Generic;
 using System.Threading;
 using System.Threading.Tasks;
 
diff --git a/Sources/EasyExtensions.Mediator/IStreamRequestHandler.cs b/Sources/EasyExtensions.Mediator/IStreamRequestHandler.cs
@@ -1,3 +1,4 @@
+using EasyExtensions.Mediator.Contracts;
 using System.Collections.Generic;
 using System.Threading;
 
diff --git a/Sources/EasyExtensions.Mediator/Mediator.cs b/Sources/EasyExtensions.Mediator/Mediator.cs
diff --git a/Sources/EasyExtensions.Mediator/NotificationHandlerExecutor.cs b/Sources/EasyExtensions.Mediator/NotificationHandlerExecutor.cs
@@ -5,12 +5,33 @@
 
 namespace EasyExtensions.Mediator
 {
+    /// <summary>
+    /// Encapsulates a notification handler instance and its associated execution callback.
+    /// </summary>
+    /// <remarks>This class is typically used to store and invoke notification handlers in a decoupled manner,
+    /// allowing for flexible execution of notification processing logic. It is commonly used in messaging or
+    /// event-driven architectures where notifications are dispatched to multiple handlers.</remarks>
     public class NotificationHandlerExecutor
     {
+        /// <summary>
+        /// Gets the instance of the handler associated with this object.
+        /// </summary>
         public object HandlerInstance { get; }
-        public Func<INotification, CancellationToken, Task> HandlerCallback { get; }
 
+        /// <summary>
+        /// Gets the callback function that handles incoming notifications asynchronously.
+        /// </summary>
+        /// <remarks>The callback is invoked with the notification to process and a cancellation token
+        /// that can be used to observe cancellation requests. The function should return a task that completes when the
+        /// notification has been handled.</remarks>
+        public Func<INotification, CancellationToken, Task> HandlerCallback { get; }
 
+        /// <summary>
+        /// Initializes a new instance of the NotificationHandlerExecutor class with the specified handler instance and
+        /// callback.
+        /// </summary>
+        /// <param name="handlerInstance">The object instance that contains the notification handler logic. Cannot be null.</param>
+        /// <param name="handlerCallback">A delegate that represents the asynchronous callback to invoke when handling a notification. Cannot be null.</param>
         public NotificationHandlerExecutor(object handlerInstance, Func<INotification, CancellationToken, Task> handlerCallback)
         {
             HandlerInstance = handlerInstance;
diff --git a/Sources/EasyExtensions.Mediator/Registration/ServiceRegistrar.cs b/Sources/EasyExtensions.Mediator/Registration/ServiceRegistrar.cs
@@ -285,7 +285,25 @@ private static (Type Service, Type Implementation) GetConcreteRegistrationTypes(
             return combinations.Select(types => requestGenericTypeDefinition.MakeGenericType(types.ToArray())).ToList();
         }
 
-        // Method to generate combinations recursively
+        /// <summary>
+        /// Generates all possible combinations by selecting one type from each list of types, producing a list of type
+        /// combinations suitable for generic type construction.
+        /// </summary>
+        /// <remarks>This method is typically used to generate all possible sets of type arguments for a
+        /// generic type, given multiple candidate types for each parameter. The number of combinations grows
+        /// multiplicatively with the size of the input lists, so use caution with large inputs. The operation can be
+        /// cancelled via the provided cancellation token.</remarks>
+        /// <param name="requestType">The generic type definition for which combinations are being generated. Used for validation and exception
+        /// messages.</param>
+        /// <param name="lists">A list of lists, where each inner list contains possible types for a corresponding generic type parameter.
+        /// Each combination will select one type from each inner list.</param>
+        /// <param name="depth">The current recursion depth. This parameter is used internally and should typically be left at its default
+        /// value.</param>
+        /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
+        /// <returns>A list of combinations, where each combination is a list of types representing one possible selection of
+        /// types from the input lists. The result will be empty if any input list is empty.</returns>
+        /// <exception cref="ArgumentException">Thrown if the number of generic type parameters exceeds the allowed maximum, if any inner list exceeds the
+        /// allowed maximum length, or if the total number of combinations exceeds the allowed maximum.</exception>
         public static List<List<Type>> GenerateCombinations(Type requestType, List<List<Type>> lists, int depth = 0, CancellationToken cancellationToken = default)
         {
             if (depth == 0)
diff --git a/Sources/EasyExtensions.Mediator/TypeForwardings.cs b/Sources/EasyExtensions.Mediator/TypeForwardings.cs
diff --git a/Sources/EasyExtensions.Mediator/Wrappers/RequestHandlerWrapper.cs b/Sources/EasyExtensions.Mediator/Wrappers/RequestHandlerWrapper.cs
@@ -2,35 +2,106 @@
 using System.Linq;
 using System.Threading;
 using System.Threading.Tasks;
+using EasyExtensions.Mediator.Contracts;
 using Microsoft.Extensions.DependencyInjection;
 
 namespace EasyExtensions.Mediator.Wrappers
 {
+    /// <summary>
+    /// Provides a base class for handling requests in an asynchronous manner.
+    /// </summary>
+    /// <remarks>Implement this class to define custom request handling logic. Derived classes should override
+    /// the Handle method to process incoming requests using the provided service provider and cancellation
+    /// token.</remarks>
     public abstract class RequestHandlerBase
     {
+        /// <summary>
+        /// Handles the specified request asynchronously using the provided service provider and cancellation token.
+        /// </summary>
+        /// <param name="request">The request object to be processed. The type and structure of this object determine how the request is
+        /// handled.</param>
+        /// <param name="serviceProvider">The service provider used to resolve dependencies required to process the request. Cannot be null.</param>
+        /// <param name="cancellationToken">A token that can be used to cancel the operation.</param>
+        /// <returns>A task that represents the asynchronous operation. The task result contains the response object, or null if
+        /// no response is produced.</returns>
         public abstract Task<object?> Handle(object request, IServiceProvider serviceProvider,
             CancellationToken cancellationToken);
     }
 
+    /// <summary>
+    /// Provides an abstract base class for handling requests that return a response of the specified type.
+    /// </summary>
+    /// <typeparam name="TResponse">The type of the response returned by the request handler.</typeparam>
     public abstract class RequestHandlerWrapper<TResponse> : RequestHandlerBase
     {
+        /// <summary>
+        /// Handles the specified request asynchronously using the provided service provider and cancellation token.
+        /// </summary>
+        /// <param name="request">The request message to be processed. Cannot be null.</param>
+        /// <param name="serviceProvider">The service provider used to resolve dependencies required to handle the request. Cannot be null.</param>
+        /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
+        /// <returns>A task that represents the asynchronous operation. The task result contains the response to the request.</returns>
         public abstract Task<TResponse> Handle(IRequest<TResponse> request, IServiceProvider serviceProvider,
             CancellationToken cancellationToken);
     }
 
+    /// <summary>
+    /// Provides an abstract base class for handling requests using a specified service provider and cancellation token.
+    /// </summary>
+    /// <remarks>This class is intended to be inherited by types that implement request handling logic. It
+    /// defines a contract for processing requests in a manner compatible with dependency injection and cancellation
+    /// patterns commonly used in .NET applications.</remarks>
     public abstract class RequestHandlerWrapper : RequestHandlerBase
     {
+        /// <summary>
+        /// Handles the specified request asynchronously using the provided service provider and cancellation token.
+        /// </summary>
+        /// <param name="request">The request to be processed. Must not be null.</param>
+        /// <param name="serviceProvider">The service provider used to resolve dependencies required to handle the request. Must not be null.</param>
+        /// <param name="cancellationToken">A token that can be used to cancel the operation.</param>
+        /// <returns>A task that represents the asynchronous operation. The task result contains a <see cref="Unit"/> value upon
+        /// completion.</returns>
         public abstract Task<Unit> Handle(IRequest request, IServiceProvider serviceProvider,
             CancellationToken cancellationToken);
     }
 
+    /// <summary>
+    /// Provides an implementation of a request handler wrapper for handling requests and responses using the specified
+    /// request and response types.
+    /// </summary>
+    /// <remarks>This class enables the execution of request handlers and associated pipeline behaviors for a
+    /// given request and response type. It is typically used internally by the MediatR framework to facilitate dynamic
+    /// invocation of request handlers and pipeline behaviors. Thread safety and lifetime management depend on the
+    /// underlying service provider and registered handlers.</remarks>
+    /// <typeparam name="TRequest">The type of the request message. Must implement <see cref="IRequest{TResponse}"/>.</typeparam>
+    /// <typeparam name="TResponse">The type of the response returned by the handler.</typeparam>
     public class RequestHandlerWrapperImpl<TRequest, TResponse> : RequestHandlerWrapper<TResponse>
         where TRequest : IRequest<TResponse>
     {
+        /// <summary>
+        /// Handles the specified request using the provided service provider and cancellation token.
+        /// </summary>
+        /// <param name="request">The request object to be handled. Must implement the <see cref="IRequest{TResponse}"/> interface.</param>
+        /// <param name="serviceProvider">The service provider used to resolve dependencies required to process the request.</param>
+        /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
+        /// <returns>A task that represents the asynchronous operation. The task result contains the response produced by
+        /// handling the request, or <see langword="null"/> if no response is produced.</returns>
         public override async Task<object?> Handle(object request, IServiceProvider serviceProvider,
             CancellationToken cancellationToken) =>
             await Handle((IRequest<TResponse>)request, serviceProvider, cancellationToken).ConfigureAwait(false);
 
+        /// <summary>
+        /// Handles the specified request by invoking the appropriate request handler and applying all configured
+        /// pipeline behaviors in order.
+        /// </summary>
+        /// <remarks>Pipeline behaviors are executed in reverse registration order, wrapping the request
+        /// handler. This method resolves all required services from the provided <paramref
+        /// name="serviceProvider"/>.</remarks>
+        /// <param name="request">The request message to be handled. Must implement <see cref="IRequest{TResponse}"/>.</param>
+        /// <param name="serviceProvider">The service provider used to resolve the request handler and pipeline behaviors.</param>
+        /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
+        /// <returns>A task that represents the asynchronous operation. The task result contains the response produced by the
+        /// request handler after all pipeline behaviors have been applied.</returns>
         public override Task<TResponse> Handle(IRequest<TResponse> request, IServiceProvider serviceProvider,
             CancellationToken cancellationToken)
         {
@@ -45,13 +116,42 @@ Task<TResponse> Handler(CancellationToken t = default) => serviceProvider.GetReq
         }
     }
 
+    /// <summary>
+    /// Provides a wrapper implementation for handling requests of a specific type using the MediatR pipeline and
+    /// service provider.
+    /// </summary>
+    /// <remarks>This class is typically used internally by the MediatR framework to invoke request handlers
+    /// and pipeline behaviors for a given request type. It resolves the appropriate <see
+    /// cref="IRequestHandler{TRequest}"/> and any registered <see cref="IPipelineBehavior{TRequest, Unit}"/> instances
+    /// from the provided <see cref="IServiceProvider"/>.</remarks>
+    /// <typeparam name="TRequest">The type of request to handle. Must implement <see cref="IRequest"/>.</typeparam>
     public class RequestHandlerWrapperImpl<TRequest> : RequestHandlerWrapper
         where TRequest : IRequest
     {
+        /// <summary>
+        /// Handles the specified request using the provided service provider and cancellation token.
+        /// </summary>
+        /// <param name="request">The request object to be handled. Must implement the IRequest interface.</param>
+        /// <param name="serviceProvider">The service provider used to resolve dependencies required to handle the request.</param>
+        /// <param name="cancellationToken">A token that can be used to cancel the operation.</param>
+        /// <returns>A task that represents the asynchronous operation. The task result contains the response object, or null if
+        /// no response is produced.</returns>
         public override async Task<object?> Handle(object request, IServiceProvider serviceProvider,
             CancellationToken cancellationToken) =>
             await Handle((IRequest)request, serviceProvider, cancellationToken).ConfigureAwait(false);
 
+        /// <summary>
+        /// Handles the specified request by invoking the appropriate request handler and applying all configured
+        /// pipeline behaviors asynchronously.
+        /// </summary>
+        /// <remarks>Pipeline behaviors are executed in reverse registration order, wrapping the request
+        /// handler. All dependencies are resolved from the provided <paramref name="serviceProvider"/>. The request is
+        /// cast to <typeparamref name="TRequest"/> before handling.</remarks>
+        /// <param name="request">The request message to be handled. Must be of type <typeparamref name="TRequest"/>.</param>
+        /// <param name="serviceProvider">The service provider used to resolve the request handler and pipeline behaviors.</param>
+        /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
+        /// <returns>A task that represents the asynchronous operation. The task result contains a <see cref="Unit"/> value when
+        /// the request has been handled.</returns>
         public override Task<Unit> Handle(IRequest request, IServiceProvider serviceProvider,
             CancellationToken cancellationToken)
         {
diff --git a/Sources/EasyExtensions.Mediator/Wrappers/StreamRequestHandlerWrapper.cs b/Sources/EasyExtensions.Mediator/Wrappers/StreamRequestHandlerWrapper.cs
@@ -5,6 +5,7 @@
 using System.Runtime.CompilerServices;
 using System.Threading;
 using System.Threading.Tasks;
+using EasyExtensions.Mediator.Contracts;
 
 namespace EasyExtensions.Mediator.Wrappers
 {
@@ -50,8 +51,7 @@ IAsyncEnumerable<TResponse> Handler() => serviceProvider
                         (TRequest)request,
                         () => NextWrapper(next(), cancellationToken),
                         cancellationToken
-                    )
-                )();
+                    ))();
 
             await foreach (var item in items.WithCancellation(cancellationToken))
             {

Original file line number	Diff line number	Diff line change
`@@ -3,7 +3,5 @@ namespace EasyExtensions.Mediator`
`3`	`3`	`/// <summary>`
`4`	`4`	`/// Defines a mediator to encapsulate request/response and publishing interaction patterns`
`5`	`5`	`/// </summary>`
`6`		`- public interface IMediator : ISender, IPublisher`
`7`		`- {`
`8`		`- }`
	`6`	`+ public interface IMediator : ISender, IPublisher { }`
`9`	`7`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+using EasyExtensions.Mediator.Contracts;`
`1`	`2`	`using System.Threading;`
`2`	`3`	`using System.Threading.Tasks;`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+using EasyExtensions.Mediator.Contracts;`
`1`	`2`	`using System.Collections.Generic;`
`2`	`3`	`using System.Threading;`
`3`	`4`