dohertj2/mxaccessgw
1
0
Fork 0
Code Issues 14 Pull Requests 2 Actions Packages Projects Releases Wiki Activity

docs(src): add missing XML docs and strip tracking-ID comments

Browse Source 
Sweep of 203 source files resolving CommentChecker findings: add
<summary>/<param>/<returns>/<inheritdoc> where missing, and remove
resolved task/issue tracking markers (Tests-NNN, Worker-NNN, Server-NNN,
Task N) from code comments. Comment/doc-only — no logic changes.
Server+Tests build clean under TreatWarningsAsErrors.
This commit is contained in:
Joseph Doherty
2026-07-07 14:09:49 -04:00
parent 8914472706
commit fca978de07
203 changed files with 1834 additions and 1383 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/FailoverAlarmConsumerTests.cs
+38 -9
View File
@@ -24,6 +24,7 @@ public sealed class FailoverAlarmConsumerTests
/// </summary>
private sealed class FlakyPrimary : IMxAccessAlarmConsumer
{
/// <summary>Raised when the fake forwards a simulated alarm transition via <see cref="Raise"/>.</summary>
public event EventHandler<MxAlarmTransitionEvent>? AlarmTransitionEmitted;
public bool ThrowOnPoll = true;
@@ -32,7 +33,7 @@ public sealed class FailoverAlarmConsumerTests
/// When set, <see cref="PollOnce"/> throws
/// <see cref="OutOfMemoryException"/> instead of a
/// <see cref="System.Runtime.InteropServices.COMException"/>, to
/// exercise the OOM-safe exception filter (Worker.Tests-032).
/// exercise the OOM-safe exception filter.
/// </summary>
public bool ThrowOutOfMemoryOnPoll;
@@ -45,6 +46,7 @@ public sealed class FailoverAlarmConsumerTests
/// </summary>
public int SubscribeCount;
/// <inheritdoc />
public void Subscribe(string s)
{
SubscribeCount++;
@@ -54,6 +56,7 @@ public sealed class FailoverAlarmConsumerTests
}
}
/// <inheritdoc />
public void PollOnce()
{
Polls++;
@@ -68,14 +71,20 @@ public sealed class FailoverAlarmConsumerTests
}
}
/// <inheritdoc />
public int AcknowledgeByGuid(Guid g, string c, string a, string b, string d, string e) => 11;
/// <inheritdoc />
public int AcknowledgeByName(string n, string p, string gr, string c, string a, string b, string d, string e) => 11;
/// <inheritdoc />
public IReadOnlyList<MxAlarmSnapshotRecord> SnapshotActiveAlarms() => Array.Empty<MxAlarmSnapshotRecord>();
/// <inheritdoc />
public void Dispose() { }
/// <summary>Raises <see cref="AlarmTransitionEmitted"/> with the given event, simulating a COM-forwarded transition.</summary>
/// <param name="e">The transition event to forward.</param>
public void Raise(MxAlarmTransitionEvent e) => AlarmTransitionEmitted?.Invoke(this, e);
}
@@ -85,27 +94,33 @@ public sealed class FailoverAlarmConsumerTests
/// </summary>
private sealed class StubStandby : IMxAccessAlarmConsumer
{
/// <summary>Raised when the fake forwards a simulated alarm transition via <see cref="Raise"/>.</summary>
public event EventHandler<MxAlarmTransitionEvent>? AlarmTransitionEmitted;
public bool Subscribed;
/// <summary>
/// When set, <see cref="SnapshotActiveAlarms"/> throws — modeling a
/// priming-snapshot failure during failover (Worker-026).
/// priming-snapshot failure during failover.
/// </summary>
public bool ThrowOnSnapshot;
/// <summary>Number of <see cref="SnapshotActiveAlarms"/> calls.</summary>
public int SnapshotCalls;
/// <inheritdoc />
public void Subscribe(string s) => Subscribed = true;
/// <inheritdoc />
public void PollOnce() { }
/// <inheritdoc />
public int AcknowledgeByGuid(Guid g, string c, string a, string b, string d, string e) => 22;
/// <inheritdoc />
public int AcknowledgeByName(string n, string p, string gr, string c, string a, string b, string d, string e) => 22;
/// <inheritdoc />
public IReadOnlyList<MxAlarmSnapshotRecord> SnapshotActiveAlarms()
{
SnapshotCalls++;
@@ -117,8 +132,11 @@ public sealed class FailoverAlarmConsumerTests
return Array.Empty<MxAlarmSnapshotRecord>();
}
/// <inheritdoc />
public void Dispose() { }
/// <summary>Raises <see cref="AlarmTransitionEmitted"/> with the given event, simulating a COM-forwarded transition.</summary>
/// <param name="e">The transition event to forward.</param>
public void Raise(MxAlarmTransitionEvent e) => AlarmTransitionEmitted?.Invoke(this, e);
}
@@ -128,6 +146,7 @@ public sealed class FailoverAlarmConsumerTests
PreviousState = MxAlarmStateKind.Unspecified,
};
/// <summary>Proves that the consumer switches to the subtag standby after the primary fails the configured threshold of consecutive times.</summary>
[Fact]
public void Primary_FailsThresholdTimes_SwitchesToSubtag()
{
@@ -154,6 +173,7 @@ public sealed class FailoverAlarmConsumerTests
Assert.Equal(unchecked((int)0x80004005), changes[0].HResult);
}
/// <summary>Proves that once failed over, transitions raised by the standby are forwarded through the consumer's <c>AlarmTransitionEmitted</c> event.</summary>
[Fact]
public void AfterSwitch_StandbyTransitionsAreForwarded()
{
@@ -174,6 +194,7 @@ public sealed class FailoverAlarmConsumerTests
Assert.Same(transition, forwarded);
}
/// <summary>Proves that once the primary heals, the consumer fails back to it only after the configured number of consecutive clean probes.</summary>
[Fact]
public void WhileDegraded_PrimaryHeals_FailsBackAfterStableProbes()
{
@@ -212,6 +233,7 @@ public sealed class FailoverAlarmConsumerTests
Assert.Equal(subscribeCountAfterFailover, primary.SubscribeCount);
}
/// <summary>Proves that before any failover, transitions raised by the primary are forwarded but transitions from the inactive standby are suppressed.</summary>
[Fact]
public void BeforeFailover_PrimaryTransitionsAreForwarded()
{
@@ -252,7 +274,7 @@ public sealed class FailoverAlarmConsumerTests
FailoverSettings settings = new FailoverSettings(threshold: 1, probeIntervalSeconds: 0, stableProbes: 3);
using FailoverAlarmConsumer sut = new FailoverAlarmConsumer(primary, standby, settings);
sut.Subscribe(@"\\HOST\Galaxy!Area"); // Subscribe attempt #1 (throws) → Subtag
sut.Subscribe(@"\\HOST\Galaxy!Area"); // Subscribe attempt (throws) → Subtag
// Capture how many Subscribe calls the initial setup caused (exactly 1:
// the attempt that threw and triggered failover).
@@ -272,6 +294,7 @@ public sealed class FailoverAlarmConsumerTests
Assert.Equal(subscribeCountAfterSetup, primary.SubscribeCount);
}
/// <summary>Proves that acknowledgment calls delegate to whichever child (primary or standby) is currently active.</summary>
[Fact]
public void Acknowledge_DelegatesToActiveChild()
{
@@ -325,7 +348,7 @@ public sealed class FailoverAlarmConsumerTests
}
/// <summary>
/// Worker-026 regression: when the standby's priming
/// When the standby's priming
/// <c>SnapshotActiveAlarms</c> throws during failover, the switch must
/// still (a) fire <c>ProviderModeChanged</c> so the gateway learns the
/// feed went degraded, (b) leave <see cref="FailoverAlarmConsumer.Mode"/>
@@ -361,7 +384,7 @@ public sealed class FailoverAlarmConsumerTests
}
/// <summary>
/// Worker-026 regression: when a <c>ProviderModeChanged</c> subscriber's
/// When a <c>ProviderModeChanged</c> subscriber's
/// handler throws (modeling the AlarmCommandHandler's event-queue enqueue
/// overflowing at capacity), the switch must still take effect and the
/// exception must not escape the switch path into the poll loop.
@@ -389,7 +412,7 @@ public sealed class FailoverAlarmConsumerTests
}
/// <summary>
/// Worker.Tests-031 regression: with a non-zero
/// With a non-zero
/// <see cref="FailoverSettings.ProbeIntervalSeconds"/>, two back-to-back
/// <c>ProbeOnce</c> calls must throttle — the second falls inside the
/// interval and must NOT re-poll the primary. Two consecutive calls
@@ -422,7 +445,7 @@ public sealed class FailoverAlarmConsumerTests
}
/// <summary>
/// Worker.Tests-032 regression: <c>RunPrimary</c>'s
/// <c>RunPrimary</c>'s
/// <c>when (ex is not OutOfMemoryException)</c> filter must let an
/// <see cref="OutOfMemoryException"/> propagate rather than swallowing it
/// and counting it toward the failover threshold. No mode change must
@@ -447,11 +470,17 @@ public sealed class FailoverAlarmConsumerTests
}
/// <summary>
/// Worker.Tests-032 regression: <see cref="FailoverSettings"/> clamps
/// sub-1 <c>threshold</c> and <c>stableProbes</c> (and sub-0
/// Verifies that <see cref="FailoverSettings"/> clamps out-of-range
/// <c>threshold</c> and <c>stableProbes</c> values (and negative
/// <c>probeIntervalSeconds</c>) to their safe minimums so a misconfigured
/// bind cannot change failover semantics.
/// </summary>
/// <param name="threshold">The raw, possibly out-of-range threshold to construct with.</param>
/// <param name="probeInterval">The raw, possibly negative probe interval (seconds) to construct with.</param>
/// <param name="stableProbes">The raw, possibly out-of-range stable-probe count to construct with.</param>
/// <param name="expectedThreshold">The expected clamped <see cref="FailoverSettings.Threshold"/>.</param>
/// <param name="expectedProbeInterval">The expected clamped <see cref="FailoverSettings.ProbeIntervalSeconds"/>.</param>
/// <param name="expectedStableProbes">The expected clamped <see cref="FailoverSettings.StableProbes"/>.</param>
[Theory]
[InlineData(0, 0, 0, 1, 0, 1)]
[InlineData(-5, -5, -5, 1, 0, 1)]