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
@@ -7,7 +7,7 @@ using ZB.MOM.WW.ScadaBridge.SiteRuntime.Scripts;
 namespace ZB.MOM.WW.ScadaBridge.SiteRuntime.Tests.TestSupport;

 /// <summary>
-/// M1 Site Event Logging categories: a capturing fake <see cref="ISiteEventLogger"/>
+/// A capturing fake <see cref="ISiteEventLogger"/>
 /// used by the actor tests to assert that the right operational events are emitted.
 /// Thread-safe — the actors fire-and-forget <c>LogEventAsync</c> from background
 /// tasks, so multiple captures can land concurrently.
@@ -29,9 +29,12 @@ public sealed class FakeSiteEventLogger : ISiteEventLogger
    public IReadOnlyList<Entry> Entries => _entries.ToArray();

    /// <summary>Captured events filtered to a single category.</summary>
+    /// <param name="eventType">The event category to filter on.</param>
+    /// <returns>The captured events with the given category.</returns>
    public IReadOnlyList<Entry> OfType(string eventType) =>
        _entries.Where(e => e.EventType == eventType).ToArray();

+    // Captures the event so tests can assert on it.
    /// <inheritdoc />
    public Task LogEventAsync(
        string eventType,
@@ -45,6 +48,7 @@ public sealed class FakeSiteEventLogger : ISiteEventLogger
        return Task.CompletedTask;
    }

+    // Always zero for this fake.
    /// <inheritdoc />
    public long FailedWriteCount => 0;
 }
@@ -63,12 +67,12 @@ public sealed class FakeSiteEventLogger : ISiteEventLogger
 /// </summary>
 /// <param name="logger">The event logger to resolve for <see cref="ISiteEventLogger"/>.</param>
 /// <param name="optionsMonitor">
-/// WP3.2: optional <see cref="IOptionsMonitor{TOptions}"/> for <see cref="SiteRuntimeOptions"/>
+/// Optional <see cref="IOptionsMonitor{TOptions}"/> for <see cref="SiteRuntimeOptions"/>
 /// — resolves for the hot-toggle tests; null (the default) exercises the launcher's
-/// constructor-passed-options fallback, matching every pre-WP3.2 caller of this class.
+/// constructor-passed-options fallback, matching every earlier caller of this class.
 /// </param>
 /// <param name="summaryRecorder">
-/// WP3.2: optional <see cref="ScriptRunSummaryRecorder"/> — resolves so a test can assert on
+/// Optional <see cref="ScriptRunSummaryRecorder"/> — resolves so a test can assert on
 /// the aggregate counters a run produced; null (the default) exercises the launcher's
 /// null-safe skip path.
 /// </param>
@@ -82,7 +86,9 @@ public sealed class SingleServiceProvider(
    private readonly IOptionsMonitor<SiteRuntimeOptions>? _optionsMonitor = optionsMonitor;
    private readonly ScriptRunSummaryRecorder? _summaryRecorder = summaryRecorder;

-    /// <inheritdoc />
+    /// <summary>Resolves the logger, the scope factory and the optional options monitor and summary recorder.</summary>
+    /// <param name="serviceType">The service type to resolve.</param>
+    /// <returns>The matching service, or null when the type is not served.</returns>
    public object? GetService(Type serviceType)
    {
        if (serviceType == typeof(ISiteEventLogger)) return _logger;
@@ -92,12 +98,13 @@ public sealed class SingleServiceProvider(
        return null;
    }

-    /// <inheritdoc />
+    /// <summary>Creates a scope that re-exposes this provider.</summary>
+    /// <returns>This instance as the scope.</returns>
    public IServiceScope CreateScope() => this;

-    /// <inheritdoc />
+    /// <summary>Gets the provider for this scope, which is this instance.</summary>
    public IServiceProvider ServiceProvider => this;

-    /// <inheritdoc />
+    /// <summary>Does nothing; the scope owns no resources.</summary>
    public void Dispose() { }
 }
@@ -4,7 +4,7 @@ using ZB.MOM.WW.ScadaBridge.SiteEventLogging;
 namespace ZB.MOM.WW.ScadaBridge.SiteRuntime.Tests.TestSupport;

 /// <summary>
-/// WP3.1 parity pin 3: an <see cref="IServiceProvider"/> that counts
+/// An <see cref="IServiceProvider"/> that counts
 /// <see cref="IServiceScopeFactory.CreateScope"/> calls and each scope's
 /// <see cref="IDisposable.Dispose"/>, so a test can assert that one script run creates
 /// exactly one DI scope and disposes it exactly once — on the success, failure, AND timeout
@@ -24,7 +24,9 @@ public sealed class ScopeSpyServiceProvider(ISiteEventLogger? logger = null)
    /// <summary>Scope disposals observed so far (double-disposal is counted twice, deliberately).</summary>
    public int ScopesDisposed => Volatile.Read(ref _scopesDisposed);

-    /// <inheritdoc />
+    /// <summary>Resolves the site event logger and this scope factory; every other service resolves to <c>null</c>.</summary>
+    /// <param name="serviceType">The requested service type.</param>
+    /// <returns>The matching service, or <c>null</c> when unsupported.</returns>
    public object? GetService(Type serviceType)
    {
        if (serviceType == typeof(ISiteEventLogger)) return logger;
@@ -32,7 +34,8 @@ public sealed class ScopeSpyServiceProvider(ISiteEventLogger? logger = null)
        return null;
    }

-    /// <inheritdoc />
+    /// <summary>Creates a counted scope whose disposal is also counted.</summary>
+    /// <returns>A spy scope.</returns>
    public IServiceScope CreateScope()
    {
        Interlocked.Increment(ref _scopesCreated);
@@ -41,8 +44,10 @@ public sealed class ScopeSpyServiceProvider(ISiteEventLogger? logger = null)

    private sealed class SpyScope(ScopeSpyServiceProvider owner) : IServiceScope
    {
+        /// <summary>Gets the owning provider as the scope's service provider.</summary>
        public IServiceProvider ServiceProvider => owner;

+        /// <summary>Releases the resources held by this instance.</summary>
        public void Dispose() => Interlocked.Increment(ref owner._scopesDisposed);
    }
 }
@@ -5,7 +5,7 @@ namespace ZB.MOM.WW.ScadaBridge.SiteRuntime.Tests.TestSupport;
 /// <summary>
 /// Minimal <see cref="IOptionsMonitor{TOptions}"/> test double with a mutable
 /// <see cref="Set"/> so a test can flip a value mid-run and assert the NEXT read observes it
-/// — used by the WP3.2 hot-toggle tests
+/// — used by the hot-toggle tests
 /// (<c>SiteRuntimeOptions.PerRunScriptEvents</c>/<c>PerRunScriptEventScripts</c> are read via
 /// <c>IOptionsMonitor.CurrentValue</c> per run specifically so they don't need a restart).
 /// Avoids depending on <c>Microsoft.Extensions.Configuration</c>'s reload-token plumbing,
@@ -15,15 +15,20 @@ public sealed class TestOptionsMonitor<T>(T initial) : IOptionsMonitor<T>
 {
    private T _current = initial;

-    /// <inheritdoc />
+    /// <summary>Gets the current value, as most recently set by <see cref="Set"/>.</summary>
    public T CurrentValue => _current;

-    /// <inheritdoc />
+    /// <summary>Returns the current value regardless of the requested name.</summary>
+    /// <param name="name">The named-options key, ignored by this double.</param>
+    /// <returns>The current value.</returns>
    public T Get(string? name) => _current;

-    /// <inheritdoc />
+    /// <summary>Change notifications are not supported by this double; no registration is made.</summary>
+    /// <param name="listener">The change listener, ignored by this double.</param>
+    /// <returns>Always <see langword="null"/>.</returns>
    public IDisposable? OnChange(Action<T, string?> listener) => null;

    /// <summary>Replaces the current value, observed by the next <see cref="CurrentValue"/> read.</summary>
+    /// <param name="value">The new value.</param>
    public void Set(T value) => _current = value;
 }