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
@@ -20,11 +20,24 @@ namespace ZB.MOM.WW.ScadaBridge.IntegrationTests.Cluster;
/// </summary>
public sealed class TwoNodeClusterFixture : IAsyncDisposable
{
/// <summary>Gets the first cluster node, which is always started first and is therefore the oldest member.</summary>
public ActorSystem NodeA { get; private set; } = null!;
/// <summary>Gets the second cluster node, which joins after the first.</summary>
public ActorSystem NodeB { get; private set; } = null!;
/// <summary>Gets the remoting port used by the first node.</summary>
public int PortA { get; private set; }
/// <summary>Gets the remoting port used by the second node.</summary>
public int PortB { get; private set; }
/// <summary>Starts both nodes in order and waits until each sees two Up members.</summary>
/// <param name="role">The Akka role assigned to both nodes.</param>
/// <param name="stableAfter">How long membership must be stable before downing decisions; defaults to a scaled test value.</param>
/// <param name="portA">The remoting port for the first node, or null to pick a free port.</param>
/// <param name="portB">The remoting port for the second node, or null to pick a free port.</param>
/// <param name="heartbeatInterval">The failure-detector heartbeat interval; defaults to a scaled test value.</param>
/// <param name="failureDetectionThreshold">The failure-detector threshold; defaults to a scaled test value.</param>
/// <param name="strategy">The split-brain resolver strategy to configure.</param>
/// <returns>A task that yields the started two-node fixture.</returns>
public static async Task<TwoNodeClusterFixture> StartAsync(
string role = "Central", TimeSpan? stableAfter = null,
int? portA = null, int? portB = null,
@@ -45,6 +58,13 @@ public sealed class TwoNodeClusterFixture : IAsyncDisposable
/// <summary>Starts a node from production HOCON; used by StartAsync and by restart-scenarios.
/// <paramref name="strategy"/> defaults to the production posture (auto-down, decision
/// 2026-07-21); pass "keep-oldest" to exercise the legacy SBR path.</summary>
/// <param name="port">The remoting port for the node.</param>
/// <param name="role">The Akka role assigned to the node.</param>
/// <param name="stableAfter">How long membership must be stable before downing decisions; defaults to a scaled test value.</param>
/// <param name="heartbeatInterval">The failure-detector heartbeat interval; defaults to a scaled test value.</param>
/// <param name="failureDetectionThreshold">The failure-detector threshold; defaults to a scaled test value.</param>
/// <param name="strategy">The split-brain resolver strategy to configure.</param>
/// <returns>The started actor system.</returns>
public ActorSystem StartNode(int port, string role, TimeSpan? stableAfter = null,
TimeSpan? heartbeatInterval = null, TimeSpan? failureDetectionThreshold = null,
string strategy = "auto-down")
@@ -76,8 +96,15 @@ public sealed class TwoNodeClusterFixture : IAsyncDisposable
}
/// <summary>Hard-crash a node: abrupt terminate, no cluster leave.</summary>
/// <param name="node">The node to crash.</param>
/// <returns>A task that represents the asynchronous termination.</returns>
public static Task CrashNode(ActorSystem node) => node.Terminate();
/// <summary>Waits until the given system sees exactly the given number of Up members and none unreachable.</summary>
/// <param name="system">The actor system whose cluster view is polled.</param>
/// <param name="count">The expected number of Up members.</param>
/// <param name="timeout">The maximum time to wait.</param>
/// <returns>A task that completes when the expected membership is reached, or throws <see cref="TimeoutException"/> on timeout.</returns>
public static async Task WaitForMembersUp(ActorSystem system, int count, TimeSpan timeout)
{
var cluster = Akka.Cluster.Cluster.Get(system);
@@ -95,6 +122,11 @@ public sealed class TwoNodeClusterFixture : IAsyncDisposable
$"Unreachable: [{string.Join(", ", cluster.State.Unreachable)}]");
}
/// <summary>Waits until the given address is neither a member nor unreachable in the survivor's cluster view.</summary>
/// <param name="survivor">The actor system whose cluster view is polled.</param>
/// <param name="removed">The address expected to disappear from the view.</param>
/// <param name="timeout">The maximum time to wait.</param>
/// <returns>A task that completes when the member is gone, or throws <see cref="TimeoutException"/> on timeout.</returns>
public static async Task WaitForMemberRemoved(ActorSystem survivor, Address removed, TimeSpan timeout)
{
var cluster = Akka.Cluster.Cluster.Get(survivor);
@@ -109,6 +141,8 @@ public sealed class TwoNodeClusterFixture : IAsyncDisposable
throw new TimeoutException($"Member {removed} was never removed from {cluster.SelfAddress}'s view — SBR did not down it.");
}
/// <summary>Finds a free loopback TCP port.</summary>
/// <returns>A port number that was free when probed.</returns>
public static int GetFreeTcpPort()
{
var listener = new System.Net.Sockets.TcpListener(System.Net.IPAddress.Loopback, 0);
@@ -118,6 +152,8 @@ public sealed class TwoNodeClusterFixture : IAsyncDisposable
return port;
}
/// <summary>Releases the resources used by this instance asynchronously.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
public async ValueTask DisposeAsync()
{
foreach (var sys in new[] { NodeA, NodeB })