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.
2026-10-07 15:05:49 -04:00
parent 0ffd4bdbea
commit 513fa1aa16
998 changed files with 17896 additions and 2395 deletions
@@ -11,7 +11,7 @@ using ZB.MOM.WW.ScadaBridge.Commons.Types.Enums;
 namespace ZB.MOM.WW.ScadaBridge.PerformanceTests.AuditLog;

 /// <summary>
-/// Bundle D (M5-T9) / C7 (Task 2.5) hot-path latency budget for
+/// Hot-path latency budget for
 /// <see cref="ScadaBridgeAuditRedactor"/>. The redactor sits between event
 /// construction and persistence on every audit row — site SQLite hot-path and
 /// central direct-write both — so it MUST stay out of the way of script-thread
@@ -47,7 +47,7 @@ public class HotPathLatencyTests
    private const int WarmupIterations = 200;
    private const int MeasureIterations = 2_000;

-    // C3/C7 (Task 2.5): the hot-path redactor is the canonical
+    // The hot-path redactor is the canonical
    // ScadaBridgeAuditRedactor (IAuditRedactor) operating on the canonical record.
    private static ScadaBridgeAuditRedactor Filter(AuditLogOptions opts) => new(
        new StaticMonitor(opts),
@@ -231,9 +231,18 @@ public class HotPathLatencyTests
    private sealed class StaticMonitor : IOptionsMonitor<AuditLogOptions>
    {
        private readonly AuditLogOptions _value;
+        /// <summary>Creates a monitor that always returns the given options.</summary>
+        /// <param name="value">The options instance to return.</param>
        public StaticMonitor(AuditLogOptions value) => _value = value;
+        /// <summary>Gets the fixed options instance.</summary>
        public AuditLogOptions CurrentValue => _value;
+        /// <summary>Returns the fixed options instance regardless of name.</summary>
+        /// <param name="name">The options name, ignored.</param>
+        /// <returns>The fixed options instance.</returns>
        public AuditLogOptions Get(string? name) => _value;
+        /// <summary>Ignores the listener because the options never change.</summary>
+        /// <param name="listener">The change listener, ignored.</param>
+        /// <returns>Always <see langword="null"/>.</returns>
        public IDisposable? OnChange(Action<AuditLogOptions, string?> listener) => null;
    }
 }
@@ -18,16 +18,18 @@ namespace ZB.MOM.WW.ScadaBridge.PerformanceTests.Failover;
 /// member REMOVAL (detection + stability window + gossip) with singleton
 /// continuity asserted on the oldest; the oldest-crash direction is covered
 /// behaviorally by SbrFailoverTests.AutoDown_HardCrashOfOldestNode_* and by
-/// the docker failover drill. Covers overall review P2-10 / report-08 NF2
-/// and report-01 round-2 N1's measurement ask.
+/// the docker failover drill. Covers the measurement requested by the overall review.
 /// </summary>
 public class FailoverTimingTests(ITestOutputHelper output)
 {
    private sealed class EchoActor : ReceiveActor
    {
+        /// <summary>Initializes a new instance of the <see cref="EchoActor"/> class.</summary>
        public EchoActor() => ReceiveAny(msg => Sender.Tell(msg));
    }

+    /// <summary>Verifies that a hard kill of the younger node is followed by removal within the design envelope.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Trait("Category", "Performance")]
    [Fact]
    public async Task HardKillOfYoungerNode_SbrRemovalWithinDesignEnvelope()
@@ -7,13 +7,14 @@ using ZB.MOM.WW.ScadaBridge.HealthMonitoring;
 namespace ZB.MOM.WW.ScadaBridge.PerformanceTests;

 /// <summary>
-/// WP-4 (Phase 8): Performance test framework for health reporting aggregation.
+/// Performance test framework for health reporting aggregation.
 /// Verifies health reporting from 10 sites can be aggregated correctly.
 /// </summary>
 public class HealthAggregationTests
 {
    private readonly CentralHealthAggregator _aggregator;

+    /// <summary>Initializes the test class with a central health aggregator configured for 30-second reports and a 60-second offline timeout.</summary>
    public HealthAggregationTests()
    {
        var options = Options.Create(new HealthMonitoringOptions
@@ -26,6 +27,7 @@ public class HealthAggregationTests
            NullLogger<CentralHealthAggregator>.Instance);
    }

+    /// <summary>Verifies that health reports from ten sites are all tracked by the aggregator.</summary>
    [Trait("Category", "Performance")]
    [Fact]
    public void AggregateHealthReports_10Sites_AllTracked()
@@ -66,6 +68,7 @@ public class HealthAggregationTests
        Assert.All(states.Values, s => Assert.True(s.IsOnline));
    }

+    /// <summary>Verifies that the aggregator handles a high volume of rapid report updates.</summary>
    [Trait("Category", "Performance")]
    [Fact]
    public void AggregateHealthReports_RapidUpdates_HandlesVolume()
@@ -106,6 +109,7 @@ public class HealthAggregationTests
        });
    }

+    /// <summary>Verifies that stale health reports are rejected.</summary>
    [Trait("Category", "Performance")]
    [Fact]
    public void AggregateHealthReports_StaleReportsRejected()
@@ -133,6 +137,7 @@ public class HealthAggregationTests
        Assert.Equal(5, state.LatestReport!.ScriptErrorCount);
    }

+    /// <summary>Verifies that collecting a report resets the interval counters.</summary>
    [Trait("Category", "Performance")]
    [Fact]
    public void HealthCollector_CollectReport_ResetsIntervalCounters()
@@ -3,7 +3,7 @@ using System.Diagnostics;
 namespace ZB.MOM.WW.ScadaBridge.PerformanceTests;

 /// <summary>
-/// WP-4 (Phase 8): Performance test framework for staggered startup.
+/// Performance test framework for staggered startup.
 /// Target scale: 10 sites, 500 machines, 75 tags each.
 /// These are framework/scaffold tests — actual perf runs are manual.
 /// </summary>
@@ -51,6 +51,7 @@ public class StaggeredStartupTests
            $"Expected staggered startup {expectedTotalMs}ms exceeds 30s budget");
    }

+    /// <summary>Verifies that staggered startup distributes instance starts across 10 sites.</summary>
    [Trait("Category", "Performance")]
    [Fact]
    public void StaggeredStartup_DistributionAcross10Sites()
@@ -76,6 +77,7 @@ public class StaggeredStartupTests
        Assert.Equal(500, sites.Values.Sum());
    }

+    /// <summary>Verifies that 75 tags on each of 500 machines gives a total capacity of 37,500 tags.</summary>
    [Trait("Category", "Performance")]
    [Fact]
    public void TagCapacity_75TagsPer500Machines_37500Total()
@@ -36,6 +36,7 @@ public class SiteStreamThroughputTests
    {
        public static long Received;

+        /// <summary>Initializes the actor and registers the handlers that count received attribute value changes.</summary>
        public CountingActor()
        {
            // The manager Tells the raw ISiteStreamEvent record (AttributeValueChanged)
@@ -45,6 +46,8 @@ public class SiteStreamThroughputTests
        }
    }

+    /// <summary>Verifies that the site stream sustains at least 10,000 events per second to a single subscriber.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Trait("Category", "Performance")]
    [Fact]
    public async Task SiteStream_SustainsAtLeast10kEventsPerSecond_ToOneSubscriber()
@@ -3,7 +3,7 @@ using ZB.MOM.WW.ScadaBridge.LoadHarness;
 namespace ZB.MOM.WW.ScadaBridge.PerformanceTests.TargetScale;

 /// <summary>
-/// Keeps the target-scale load harness (deferred-work register #25 / Phase-8 WP-4)
+/// Keeps the target-scale load harness (a deferred-work register item)
 /// honest at CI scale.
 ///
 /// <para>
@@ -13,7 +13,7 @@ namespace ZB.MOM.WW.ScadaBridge.PerformanceTests.TargetScale;
 /// <c>dotnet test ZB.MOM.WW.ScadaBridge.slnx</c> (the <c>Category=Performance</c>
 /// trait enables a filter, it does not exclude by default), and a 20-minute test
 /// would be intolerable there. What this test protects is that the harness still
-/// compiles, wires up, and produces coherent measurements — so #25's evidence can be
+/// compiles, wires up, and produces coherent measurements — so the harness's evidence can be
 /// regenerated on demand rather than bit-rotting.
 /// </para>
 /// <para>