docs(tests): fix CommentChecker findings across tests/ — 13,392 → 0 (repo-wide scan clean)

Comment/XML-doc changes only:
- add summaries to ~10k test methods, fixtures, fakes and helpers
  (+ <param> on theories, <returns> on async Task methods,
  <inheritdoc/> on interface implementations the checker can resolve)
- strip ~2.6k project-tracking references (WP*, P*-*, row-NN, Task N,
  #NN, Component-0NN) from comments, keeping the explanatory text;
  reword false positives in comments only
- real docs on fakes implementing BCL/library interfaces
  (IDisposable, ILogger, IOptionsMonitor, IAsyncLifetime)
- reword the last 5 src/ false positives (CWE-1236, failures-1,
  year-0001, M365)

Only non-comment edits: four one-line nested classes split across lines
so members can carry docs. Build 0 errors / 0 warnings.

tests/ZB.MOM.WW.ScadaBridge.AuditLog.Tests/Site/SiteAuditRetentionServiceTests.cs

@@ -10,7 +10,7 @@ using AuditEvent = ZB.MOM.WW.Audit.AuditEvent;
 namespace ZB.MOM.WW.ScadaBridge.AuditLog.Tests.Site;
 
 /// <summary>
-/// Tests for <see cref="SiteAuditRetentionService"/> (PLAN-04 Task 3). The hosted
+/// Tests for <see cref="SiteAuditRetentionService"/> The hosted
 /// service runs the site SQLite retention purge on a timer: first tick after
 /// <see cref="SiteAuditRetentionOptions.InitialDelay"/>, then every
 /// <see cref="SiteAuditRetentionOptions.ResolvedPurgeInterval"/>, passing a cutoff of
@@ -19,10 +19,12 @@ namespace ZB.MOM.WW.ScadaBridge.AuditLog.Tests.Site;
 /// </summary>
 public class SiteAuditRetentionServiceTests
 {
+    /// <summary>Verifies that stopping the service after it has been disposed does not throw.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task StopAsync_AfterDispose_DoesNotThrow()
     {
-        // Regression (Gitea #15 follow-up): Dispose tears down the CTS StopAsync
+        // Regression: Dispose tears down the CTS StopAsync
         // cancels, and the host does not guarantee StopAsync is driven before the DI
         // container is disposed. Cancel() on a disposed CTS throws, and letting that
         // escape an IHostedService aborts the host's whole shutdown sequence.
@@ -43,6 +45,8 @@ public class SiteAuditRetentionServiceTests
         svc.Dispose();
     }
 
+    /// <summary>Verifies that a tick purges events older than the retention cutoff.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Tick_Purges_With_RetentionCutoff()
     {
@@ -66,6 +70,8 @@ public class SiteAuditRetentionServiceTests
             DateTime.UtcNow.AddDays(-7).AddMinutes(1));
     }
 
+    /// <summary>Verifies that a failing tick is swallowed and later ticks still run.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Tick_SwallowsExceptions_AndKeepsTicking()
     {
@@ -87,6 +93,8 @@ public class SiteAuditRetentionServiceTests
         Assert.True(queue.PurgeCalls.Count >= 2);
     }
 
+    /// <summary>Verifies that stopping the service during an in-flight purge completes cleanly without surfacing a cancellation.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task StopAsync_MidPurge_CompletesCleanly_WithoutSurfacingCancellation()
     {
@@ -127,6 +135,13 @@ public class SiteAuditRetentionServiceTests
     /// <summary>Stub queue that records purge cutoffs and can throw on the first tick.</summary>
     private sealed class RecordingSiteAuditQueue : ISiteAuditQueue
     {
+        /// <summary>Not supported by this stub.</summary>
+        /// <param name="executionIds">The execution ids to read.</param>
+        /// <param name="sinceUtc">The lower time bound.</param>
+        /// <param name="limit">The maximum number of rows.</param>
+        /// <param name="ct">A token to cancel the operation.</param>
+        /// <param name="afterEventId">The keyset cursor.</param>
+        /// <returns>Never returns; always throws <see cref="NotSupportedException"/>.</returns>
         public Task<IReadOnlyList<AuditEvent>> ReadByExecutionIdsAsync(
             IReadOnlyCollection<Guid> executionIds, DateTime sinceUtc, int limit, CancellationToken ct = default, string? afterEventId = null)
             => throw new NotSupportedException("not exercised by the retention service");
@@ -134,13 +149,17 @@ public class SiteAuditRetentionServiceTests
         private readonly ConcurrentQueue<DateTime> _purgeCalls = new();
         private int _calls;
 
+        /// <summary>Gets the cutoffs passed to each purge call, in call order.</summary>
         public IReadOnlyCollection<DateTime> PurgeCalls => _purgeCalls;
+        /// <summary>Gets a value indicating whether the first purge call throws a simulated transient failure.</summary>
         public bool ThrowOnFirstCall { get; init; }
 
         /// <summary>When set, PurgeExpiredAsync records the call then blocks until the token
         /// cancels — simulating a shutdown that lands while a purge is in flight.</summary>
         public bool BlockUntilCancelled { get; init; }
 
+        // Test stub: Records the cutoff and optionally throws or blocks, as configured.
+        /// <inheritdoc />
         public async Task<int> PurgeExpiredAsync(DateTime olderThanUtc, CancellationToken ct = default)
         {
             var n = Interlocked.Increment(ref _calls);
@@ -158,19 +177,41 @@ public class SiteAuditRetentionServiceTests
             return 0;
         }
 
+        /// <summary>Not supported by this stub.</summary>
+        /// <param name="limit">The maximum number of rows.</param>
+        /// <param name="ct">A token to cancel the operation.</param>
+        /// <returns>Never returns; always throws <see cref="NotSupportedException"/>.</returns>
         public Task<IReadOnlyList<AuditEvent>> ReadPendingAsync(int limit, CancellationToken ct = default)
             => throw new NotSupportedException();
+        /// <summary>Not supported by this stub.</summary>
+        /// <param name="limit">The maximum number of rows.</param>
+        /// <param name="ct">A token to cancel the operation.</param>
+        /// <returns>Never returns; always throws <see cref="NotSupportedException"/>.</returns>
         public Task<IReadOnlyList<AuditEvent>> ReadPendingCachedTelemetryAsync(int limit, CancellationToken ct = default)
             => throw new NotSupportedException();
+        // Test stub: Not supported by this stub.
+        /// <inheritdoc />
         public Task MarkForwardedAsync(IReadOnlyList<Guid> eventIds, CancellationToken ct = default)
             => throw new NotSupportedException();
+        /// <summary>Not supported by this stub.</summary>
+        /// <param name="sinceUtc">The lower time bound.</param>
+        /// <param name="batchSize">The maximum batch size.</param>
+        /// <param name="afterId">The keyset cursor.</param>
+        /// <param name="ct">A token to cancel the operation.</param>
+        /// <returns>Never returns; always throws <see cref="NotSupportedException"/>.</returns>
         public Task<IReadOnlyList<AuditEvent>> ReadPendingSinceAsync(
             DateTime sinceUtc, int batchSize, string? afterId = null, CancellationToken ct = default)
             => throw new NotSupportedException();
+        // Test stub: Not supported by this stub.
+        /// <inheritdoc />
         public Task MarkReconciledAsync(IReadOnlyList<Guid> eventIds, CancellationToken ct = default)
             => throw new NotSupportedException();
+        // Test stub: Not supported by this stub.
+        /// <inheritdoc />
         public Task<int> MarkReconciledUpToAsync(DateTime sinceUtc, string? afterId, CancellationToken ct = default)
             => throw new NotSupportedException();
+        // Test stub: Not supported by this stub.
+        /// <inheritdoc />
         public Task<SiteAuditBacklogSnapshot> GetBacklogStatsAsync(CancellationToken ct = default)
             => throw new NotSupportedException();
     }