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.
This commit is contained in:
Joseph Doherty
2026-10-07 15:05:49 -04:00
parent 0ffd4bdbea
commit 513fa1aa16
998 changed files with 17896 additions and 2395 deletions
@@ -9,7 +9,7 @@ using ZB.MOM.WW.ScadaBridge.NotificationOutbox.Kpi;
namespace ZB.MOM.WW.ScadaBridge.NotificationOutbox.Tests.Kpi;
/// <summary>
/// Tests for <see cref="NotificationOutboxKpiSampleSource"/> — the M6 KPI sample source that
/// Tests for <see cref="NotificationOutboxKpiSampleSource"/> — the KPI sample source that
/// snapshots the Notification Outbox delivery KPIs (global / per-site / per-node) into the
/// central KPI-history store.
/// </summary>
@@ -46,6 +46,7 @@ public class NotificationOutboxKpiSampleSourceTests
Microsoft.Extensions.Options.Options.Create(options),
Microsoft.Extensions.Options.Options.Create(kpiHistoryOptions));
/// <summary>Verifies that the sample source reports the notification outbox as its source.</summary>
[Fact]
public void Source_IsNotificationOutbox()
{
@@ -58,6 +59,7 @@ public class NotificationOutboxKpiSampleSourceTests
// live in the shared KpiMetrics catalog. Their VALUES are persisted in the KpiSample
// store and rendered by the trend UI, so a rename would silently orphan history —
// pin the exact historical strings here.
/// <summary>Verifies that the notification outbox metric catalog preserves its historical string values.</summary>
[Fact]
public void KpiMetricCatalog_NotificationOutbox_PreservesHistoricalStringValues()
{
@@ -68,6 +70,8 @@ public class NotificationOutboxKpiSampleSourceTests
Assert.Equal("oldestPendingAgeSeconds", KpiMetrics.NotificationOutbox.OldestPendingAgeSeconds);
}
/// <summary>Verifies that collecting passes cutoffs anchored on the captured-at time.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task CollectAsync_PassesCutoffsAnchoredOnCapturedAt()
{
@@ -88,6 +92,8 @@ public class NotificationOutboxKpiSampleSourceTests
expectedStuckCutoff, expectedDeliveredSince, Arg.Any<CancellationToken>());
}
/// <summary>Verifies that collecting emits global, per-site and per-node samples with the expected tuples.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task CollectAsync_EmitsGlobalSiteAndNodeSamples_WithExpectedTuples()
{
@@ -152,15 +158,17 @@ public class NotificationOutboxKpiSampleSourceTests
AssertSample(samples, "oldestPendingAgeSeconds", KpiScopes.Node, "node-a", 60);
}
// P5-5 (arch-review Low): the KPI-history rollup fold sums every deliveredLastInterval
// The KPI-history rollup fold sums every deliveredLastInterval
// sample recorded in an hour, which over-counts unless each sample is a non-overlapping
// delta covering exactly one recorder tick (KpiHistoryOptions.SampleInterval). Before the
// fix, this class recorded the RAW DeliveredKpiWindow-windowed count verbatim — with a
// 15-minute DeliveredKpiWindow sampled every 1-minute SampleInterval, 60 overlapping
// 15-minute counts summed to ~15x the true hourly total. Proven against the unfixed
// computation: temporarily short-circuiting DeliveredIntervalScaleFactor to always return
// 1.0 (i.e. "record the raw count verbatim", the pre-P5-5 behavior) makes this test fail
// 1.0 (i.e. "record the raw count verbatim", the old behavior) makes this test fail
// (30 != 2); restoring the real scale factor passes it.
/// <summary>Verifies that the delivered-last-interval count is rescaled onto the KPI history sample interval.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task CollectAsync_RescalesDeliveredLastInterval_OntoKpiHistorySampleInterval()
{
@@ -191,6 +199,8 @@ public class NotificationOutboxKpiSampleSourceTests
Assert.Equal(2.0, delivered.Value, precision: 6);
}
/// <summary>Verifies that the oldest pending age is omitted when it is null.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task CollectAsync_OmitsOldestPendingAge_WhenNull()
{
@@ -219,6 +229,8 @@ public class NotificationOutboxKpiSampleSourceTests
AssertSample(samples, "deliveredLastInterval", KpiScopes.Global, null, 0);
}
/// <summary>Verifies that collecting returns an empty list, never null, when there is nothing to report.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task CollectAsync_ReturnsEmptyList_NeverNull_WhenNothingToReport()
{