Documentation modifications

adas-core.Infrastructure/Utils/CacheHostBuilderExtension.cs

@@ -13,6 +13,12 @@ namespace adas_core.Infrastructure.Utils
     /// </summary>
     public static class CacheHostBuilderExtension
     {
+        /// <summary>
+        /// Registers the cache infrastructure on the host, exposing <see cref="ICacheService"/> through a <see cref="CacheDispatcher"/> that can route to either an in-memory or Redis-backed implementation based on <see cref="CacheSettings"/>. <see cref="RedisService"/> is wired lazily so that its <see cref="RedisService.Database"/> is only resolved once the underlying connection has been established asynchronously, while <see cref="CacheService"/> is provided with an <see cref="InMemoryLockProvider"/> and <see cref="NoCacheService"/> is registered as a no-op fallback.
+        /// </summary>
+        /// <param name="hostBuilder">The <see cref="IHostBuilder"/> to extend with the cache service registrations.</param>
+        /// <returns>The same <paramref name="hostBuilder"/> instance, configured with the cache services for fluent chaining.</returns>
+        /// <!-- aidoc:v1 sig=06693b5 body=f80dd06 -->
         public static IHostBuilder UseCache(this IHostBuilder hostBuilder)
         {
             return hostBuilder.ConfigureServices((context, services) =>

adas-core.Infrastructure/Utils/CustomPointOfCareConverter.cs

@@ -22,6 +22,13 @@ public class CustomPointOfCareConverter : JsonConverter
             return objectType == typeof(PointOfCare);
         }
 
+    /// <summary>
+    /// Serializes an object to JSON, converting all enum-typed properties to their string representation rather than their underlying integer value. If <paramref name="value"/> is <c>null</c>, a JSON null token is written and the method returns immediately.
+    /// </summary>
+    /// <param name="writer">The <see cref="JsonWriter"/> that receives the serialized JSON output.</param>
+    /// <param name="value">The object to serialize. Enum properties on this instance are written as their string names.</param>
+    /// <param name="serializer">The <see cref="JsonSerializer"/> used to convert the value to a <see cref="JObject"/>.</param>
+    /// <!-- aidoc:v1 sig=0bafa81 body=109184b -->
     public override void WriteJson(JsonWriter writer, object? value, JsonSerializer serializer)
     {
         if (value == null)
@@ -45,6 +52,16 @@ public class CustomPointOfCareConverter : JsonConverter
         jo.WriteTo(writer);
     }
 
+    /// <summary>
+    /// Reads and deserializes a JSON value into an object of the target <paramref name="objectType"/>. This override is not implemented and serves as a placeholder.
+    /// </summary>
+    /// <param name="reader">The <see cref="JsonReader"/> used to read the incoming JSON tokens.</param>
+    /// <param name="objectType">The <see cref="Type"/> of the object to deserialize into.</param>
+    /// <param name="existingValue">An existing value to reuse during deserialization, or <see langword="null"/> if none is available.</param>
+    /// <param name="serializer">The <see cref="JsonSerializer"/> controlling the deserialization process.</param>
+    /// <returns>An <see cref="object"/> instance populated from the JSON data.</returns>
+    /// <exception cref="NotImplementedException">Thrown in all cases because the method body has not been implemented.</exception>
+    /// <!-- aidoc:v1 sig=c91c541 body=bfa6f2f -->
     public override object ReadJson(JsonReader reader, Type objectType, object? existingValue,
         JsonSerializer serializer)
     {

adas-core.Infrastructure/Utils/MongoDbHostBuilderExtension.cs

@@ -81,6 +81,10 @@ public static class MongoDbHostBuilderExtension
             return mongoDb;
         }
 
+    /// <summary>
+    /// Discovers all concrete types in the current <see cref="System.Reflection.Assembly"/> that implement <see cref="IEntityMapContributor"/>, instantiates each one, and invokes its <see cref="IEntityMapContributor.RegisterMaps"/> method to register entity mappings.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=e89a195 body=9c8e4ad -->
     public static void ConfigureRegisterMapClass()
     {
         var assembly = Assembly.GetExecutingAssembly();

adas-core.Infrastructure/Utils/MongoMaps/BoxConfigMapContributor.cs

@@ -15,6 +15,10 @@ namespace adas_core.Infrastructure.Utils.MongoMaps;
 /// </summary>
 public class BoxConfigMapContributor : IEntityMapContributor
 {
+    /// <summary>
+    /// Registers the BSON class maps used to control how <see cref="Box"/> and <see cref="Sensor"/> instances are serialized to and from MongoDB. Each registration is only performed when no class map is already registered for the target type, and the mappings exclude properties that should not be persisted, rename persisted members where needed, apply <see cref="DictionaryBsonConverter"/> to the <c>Configuration</c> member of <see cref="Box"/>, and configure null/default-value handling for <see cref="Sensor"/> members.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=d4dea7a body=eb04ab5 -->
     public void RegisterMaps()
     {
         if (!BsonClassMap.IsClassMapRegistered(typeof(Box)))

adas-core.Infrastructure/Utils/MongoMaps/PumpMapContributor.cs

@@ -13,6 +13,10 @@ namespace adas_core.Infrastructure.Utils.MongoMaps
     /// </summary>
     public class PumpMapContributor : IEntityMapContributor
     {
+        /// <summary>
+        /// Registers BSON class maps for the pump-related domain models (<see cref="CommonPumpTypes.PumpValue"/>, <see cref="CommonPumpTypes.SyringeDetails"/>, <see cref="PumpObservation"/>, <see cref="PumpState"/>, <see cref="PumpAlarmEvent"/>, <see cref="PumpAlarmState"/>, <see cref="ConfigPumps"/>, and <see cref="ConfigPumpItem"/>) used by the MongoDB driver. Each map is registered only when no prior registration exists for the type, optional members are configured to be ignored when null, enum properties are serialized as strings, and the <c>Id</c> member is mapped to the <c>_id</c> element where applicable.
+        /// </summary>
+        /// <!-- aidoc:v1 sig=d4dea7a body=345f688 -->
         public void RegisterMaps()
         {
             // ============================================================

adas-core.Infrastructure/Utils/MongoUtils.cs

@@ -9,6 +9,12 @@ namespace adas_core.Infrastructure.Utils;
 /// </summary>
 public class MongoUtils
 {
+    /// <summary>
+    /// Ensures that the indexes defined in <paramref name="expectedIndexes"/> are present on the <see cref="IMongoCollection{TDocument}"/> supplied via <paramref name="collection"/>. For each expected index, an existing index with the same key specification is left unchanged when its options match, or dropped and recreated when they differ (except for the built-in <c>_id_</c> index, which is never dropped); if no matching index exists the index is created, and MongoDB conflicts reported with code 85 are logged and tolerated.
+    /// </summary>
+    /// <param name="collection">The <see cref="IMongoCollection{TDocument}"/> whose indexes are inspected and reconciled.</param>
+    /// <param name="expectedIndexes">The set of <see cref="CreateIndexModel{TDocument}"/> definitions that the collection should contain.</param>
+    /// <!-- aidoc:v1 sig=e61054a body=29c4862 -->
     public static async Task EnsureIndexes<TDocument>(IMongoCollection<TDocument> collection,
         List<CreateIndexModel<TDocument>> expectedIndexes)
     {
@@ -74,6 +80,16 @@ public class MongoUtils
         }
     }
 
+    /// <summary>
+    /// Determines whether the options of an existing index match the expected <see cref="CreateIndexModel{TDocument}"/> options by comparing the <c>unique</c>, <c>background</c>, and <c>partialFilterExpression</c> values.
+    /// Missing boolean fields in <paramref name="existingIndex"/> are treated as <c>false</c>.
+    /// </summary>
+    /// <typeparam name="TDocument">The type of the document the index is defined on.</typeparam>
+    /// <param name="expectedIndexModel">The <see cref="CreateIndexModel{TDocument}"/> containing the expected <c>Unique</c>, <c>Background</c>, and <c>PartialFilterExpression</c> values.</param>
+    /// <param name="existingIndex">The <see cref="BsonDocument"/> representing the existing index whose options should be checked.</param>
+    /// <param name="renderArgs">The <see cref="RenderArgs{TDocument}"/> used to render the expected partial filter expression for comparison.</param>
+    /// <returns><c>true</c> if the unique flag, background flag, and rendered partial filter expression all match the expected values; otherwise <c>false</c>.</returns>
+    /// <!-- aidoc:v1 sig=04d4638 body=0088af8 -->
     private static bool IndexOptionsMatch<TDocument>(CreateIndexModel<TDocument> expectedIndexModel,
         BsonDocument existingIndex, RenderArgs<TDocument> renderArgs)
     {

adas-core.Infrastructure/Utils/RabbitConsumerErrorStrategy.cs

@@ -48,6 +48,15 @@ public class RabbitConsumerErrorHandler(IPublisherService publisherService)
             }
         }
 
+    /// <summary>
+    /// Handles retry processing for a received message, either forwarding it to an error queue when the maximum retry count is exceeded or republishing it to the original queue with an incremented retry counter.
+    /// </summary>
+    /// <param name="receivedInfo">Metadata about the message origin, used to determine the source queue and to build the error message.</param>
+    /// <param name="properties">The current <see cref="MessageProperties"/> of the message; its headers are copied so the retry count can be updated without mutating the original instance.</param>
+    /// <param name="body">The raw message payload that will be resent to the queue or forwarded to the error queue.</param>
+    /// <param name="exception">The <see cref="Exception"/> that triggered the retry, included when building the error message.</param>
+    /// <exception cref="Exception">Thrown when the republish to the original queue fails (i.e. <see cref="publisherService"/>.SendMessage returns <c>false</c>). The exception is caught and logged internally.</exception>
+    /// <!-- aidoc:v1 sig=d9b4e83 body=c5b7128 -->
     private void HandleRetries(
         MessageReceivedInfo receivedInfo,
         MessageProperties properties,

adas-core.Infrastructure/Utils/TypesUtils.cs

@@ -25,6 +25,15 @@ public static class TypesUtils
             };
         }
 
+    /// <summary>
+    /// Resolves the <see cref="System.Type"/> of a device driver class by locating a loaded assembly whose name contains <paramref name="typeName"/> and then loading the type at the path formed by replacing hyphens in <paramref name="typeName"/> with underscores and appending <c>.Devices.</c>, <paramref name="device"/>, and <paramref name="deviceType"/>.
+    /// </summary>
+    /// <param name="typeName">Substring used to match the loaded assembly and to build the namespace portion of the target type name.</param>
+    /// <param name="device">Device identifier segment combined into the target class name.</param>
+    /// <param name="deviceType">Suffix appended to <paramref name="device"/> to form the final class name.</param>
+    /// <returns>The resolved <see cref="System.Type"/> representing the device driver class.</returns>
+    /// <exception cref="AdasException">Thrown when no loaded assembly matches <paramref name="typeName"/> or when the driver type cannot be resolved within the matched assembly.</exception>
+    /// <!-- aidoc:v1 sig=3e9123d body=6bc0688 -->
     private static Type GetType(string typeName, string device, string deviceType)
     {
         var loadedAssemblies = AppDomain.CurrentDomain.GetAssemblies();