Documentation modifications

adas-core.Test/Services/CacheDispatcherTest.cs

@@ -42,6 +42,10 @@ public class FakeLockProvider : ILockProvider
 /// </remarks>
 public class FakeLockManagerService : LockManagerService
 {
+    /// <summary>
+    /// Initializes a new instance of <see cref="FakeLockManagerService"/>, a test fake of <see cref="LockManagerService"/>, by forwarding a mocked <see cref="ILogger{LockManagerService}"/> and a <see cref="FakeLockProvider"/> to the base constructor.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=1d9bbc1 body=4448e1d -->
     public FakeLockManagerService() : base(
         Mock.Of<ILogger<LockManagerService>>(),
         new FakeLockProvider())
@@ -61,6 +65,10 @@ public class FakeRedisService : RedisService, ICacheService
     public bool WasCalled { get; private set; }
     public string? LastKey { get; private set; }
 
+    /// <summary>
+    /// Initializes a new instance of <see cref="FakeRedisService"/>, a test double for <see cref="RedisService"/>, supplying default <see cref="CacheSettings"/>, a mocked <see cref="ILogger{RedisService}"/>, and a <see cref="FakeLockManagerService"/> to the base constructor.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=82d8847 body=4448e1d -->
     public FakeRedisService() : base(
         Options.Create(new CacheSettings()),
         Mock.Of<ILogger<RedisService>>(),
@@ -123,10 +131,23 @@ public class FakeCacheService : CacheService, ICacheService
     public bool WasCalled { get; private set; }
     public string? LastKey { get; private set; }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FakeCacheService"/> test double, supplying a newly created <see cref="FakeLockManagerService"/> to the base cache service as its lock-management dependency.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=e01af03 body=4448e1d -->
     public FakeCacheService() : base(new FakeLockManagerService())
     {
     }
 
+    /// <summary>
+    /// Stub implementation of <see cref="ICacheService.GetOrSetObjectAsync{T}"/> that records the invocation and the supplied key without performing any caching, and returns the value produced by <paramref name="factory"/>.
+    /// </summary>
+    /// <param name="key">The cache key under which the value would be stored; recorded for later verification.</param>
+    /// <param name="factory">The <see cref="Func{Task{T}}"/> invoked to produce the value returned by this method.</param>
+    /// <param name="ttl">Optional time-to-live for the cache entry; ignored by this implementation.</param>
+    /// <param name="cancellationToken">Token to cancel the operation; ignored by this implementation.</param>
+    /// <returns>The <see cref="Task{T}"/> produced by invoking <paramref name="factory"/>.</returns>
+    /// <!-- aidoc:v1 sig=f7027e3 body=b366c2a -->
     Task<T> ICacheService.GetOrSetObjectAsync<T>(
         string key,
         Func<Task<T>> factory,
@@ -138,6 +159,17 @@ public class FakeCacheService : CacheService, ICacheService
         return factory();
     }
 
+    /// <summary>
+    /// Retrieves an object from the cache for the given <paramref name="groupedField"/> and <paramref name="patientId"/>, or produces it via <paramref name="factory"/> when no cached entry exists. This implementation unconditionally invokes <paramref name="factory"/> and records the call by setting <see cref="WasCalled"/> to <c>true</c>, ignoring any cached value and the <paramref name="ttl"/>.
+    /// </summary>
+    /// <typeparam name="T">The type of the object being retrieved or created.</typeparam>
+    /// <param name="groupedField">The grouped field used as part of the cache lookup key.</param>
+    /// <param name="patientId">The patient identifier used as part of the cache lookup key.</param>
+    /// <param name="factory">The asynchronous factory invoked to produce the value when no cached entry is available.</param>
+    /// <param name="ttl">An optional time-to-live for the cached entry. Not used by this implementation.</param>
+    /// <param name="cancellationToken">A <see cref="CancellationToken"/> to cancel the operation.</param>
+    /// <returns>A <see cref="Task{T}"/> that resolves to the value returned by <paramref name="factory"/>.</returns>
+    /// <!-- aidoc:v1 sig=efeef03 body=0bb8f50 -->
     Task<T> ICacheService.GetOrSetObjectAsync<T>(
         GroupedField groupedField,
         ObjectId patientId,
@@ -186,6 +218,10 @@ public class FakeNoCacheService : NoCacheService, ICacheService
 }
 
 
+/// <summary>
+/// Represents a test fixture that exercises the <see cref="CacheDispatcher"/> to validate its expected runtime behavior.
+/// </summary>
+/// <!-- aidoc:v1 sig=e92eb06 -->
 [TestFixture]
 public class CacheDispatcherTest
 {
@@ -216,6 +252,10 @@ public class CacheDispatcherTest
 
     #region TC-23
 
+    /// <summary>
+    /// Verifies that GetOrSetObjectAsync uses the Redis service when the patients cache mode is configured as <see cref="CacheEnum.Mode.Redis"/>, and does not fall back to the memory or no-op cache services.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=3f07bc5 body=9d2c439 -->
     [Test]
     public async Task GetOrSetObjectAsync_UsesRedisService_WhenPatientsModeIsRedis()
     {
@@ -238,6 +278,10 @@ public class CacheDispatcherTest
     #endregion
 
     #region TC-24
+    /// <summary>
+    /// Verifies that <see cref="CacheDispatcher.GetOrSetObjectAsync{T}"/> delegates to the in-memory cache service when <see cref="CacheSettings.Appointments"/> is set to <see cref="CacheEnum.Mode.Cache"/>, forwarding the supplied key and ensuring that neither the Redis nor the no-op cache implementations are invoked in this scenario.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=69efd2a body=e0ce152 -->
     [Test]
     public async Task GetOrSetObjectAsync_UsesCacheService_WhenAppointmentsModeIsCache()
     {
@@ -260,6 +304,10 @@ public class CacheDispatcherTest
     #endregion
 
     #region TC-25
+    /// <summary>
+    /// Verifies that <see cref="CacheDispatcher.GetOrSetObjectAsync"/> delegates to the no-op cache service and skips both the Redis and in-memory cache services when <see cref="CacheSettings.PumpObservations"/> is configured with <see cref="CacheEnum.Mode.None"/>.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=c516b35 body=f3aa2f5 -->
     [Test]
     public async Task GetOrSetObjectAsync_UsesNoCacheService_WhenPumpObservationsModeIsNone()
     {
@@ -282,6 +330,13 @@ public class CacheDispatcherTest
     #endregion
 
     #region TC-26
+    /// <summary>
+    /// Verifies that <see cref="GetOrSetObjectAsync{T}(string, Func{Task{T}})"/> falls back to the InMemory cache service
+    /// when the provided cache key has an unrecognized prefix, ensuring that unknown keys are still served by the default
+    /// cache implementation rather than the <see cref="IRedisCacheService"/> or <see cref="INoCacheService"/>.
+    /// </summary>
+    /// <returns>A <see cref="Task"/> that completes when the fallback behavior has been validated through the assertions.</returns>
+    /// <!-- aidoc:v1 sig=b24df70 body=15e546d -->
     [Test]
     public async Task GetOrSetObjectAsync_UsesCacheService_WhenKeyIsUnrecognized()
     {