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.Tests/Alarms/AlarmFailoverEndToEndTests.cs
+7
View File
@@ -32,6 +32,8 @@ public sealed class AlarmFailoverEndToEndTests
{
private static readonly TimeSpan WaitTimeout = TimeSpan.FromSeconds(30);
/// <summary>Verifies the alarm feed reflects each stage of a full alarmmgr-to-subtag failover and failback lifecycle.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ProviderFailoverAndFailback_FullLifecycle_ReflectedInFeed()
{
@@ -227,6 +229,8 @@ public sealed class AlarmFailoverEndToEndTests
await monitor.StopAsync(CancellationToken.None);
}
/// <summary>Verifies a degraded transition cached before a new subscriber connects is replayed with its degraded flag and source provider intact.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task DegradedTransition_CachedThenReplayed_CarriesDegradedAndSourceProviderToNewSubscriber()
{
@@ -400,10 +404,13 @@ public sealed class AlarmFailoverEndToEndTests
public SubscribeAlarmsCommand? LastSubscribeCommand { get; private set; }
/// <summary>Pushes a worker event onto the monitor's event stream.</summary>
/// <param name="mxEvent">The worker event to push.</param>
public void EmitEvent(MxEvent mxEvent) =>
_events.Writer.TryWrite(new WorkerEvent { Event = mxEvent });
/// <summary>Completes once the monitor has issued its SubscribeAlarms command.</summary>
/// <param name="timeout">The maximum time to wait.</param>
/// <returns>A task that completes once the SubscribeAlarms command has been issued.</returns>
public Task WaitForSubscribeAsync(TimeSpan timeout) => _subscribed.Task.WaitAsync(timeout);
/// <inheritdoc />
src/ZB.MOM.WW.MxGateway.Tests/Alarms/AlarmWatchListResolverTests.cs
+76 -17
View File
@@ -39,6 +39,12 @@ public sealed class AlarmWatchListResolverTests
},
};
/// <summary>
/// Verifies Galaxy Repository rows and config includes are unioned, configured
/// excludes are removed, and duplicate references (case-insensitive) collapse
/// to a single entry.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ResolveAsync_UnionsGalaxyRowsAndIncludes_RemovesExcludes_AndDeduplicates()
{
@@ -63,6 +69,8 @@ public sealed class AlarmWatchListResolverTests
Assert.Equal(3, result.Count);
}
/// <summary>Verifies subtag item addresses are composed using the configured subtag names.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ResolveAsync_ComposesSubtagAddressesFromConfigNames()
{
@@ -89,6 +97,8 @@ public sealed class AlarmWatchListResolverTests
Assert.Equal("Tank01.Level.HiHi.AckCmt", target.AckCommentSubtag);
}
/// <summary>Verifies that configuring empty Priority and AckComment subtag names leaves those target fields empty.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ResolveAsync_EmptyPriorityAndAckComment_LeaveThoseFieldsEmpty()
{
@@ -110,6 +120,8 @@ public sealed class AlarmWatchListResolverTests
Assert.Equal(string.Empty, target.AckCommentSubtag);
}
/// <summary>Verifies the canonical full reference uses the row's discovered Galaxy area, not the configured Discovery.Area.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ResolveAsync_ComposesCanonicalFullReference_FromRealGalaxyArea_NotConfigArea()
{
@@ -135,6 +147,8 @@ public sealed class AlarmWatchListResolverTests
Assert.Equal("Galaxy!TestArea.TestMachine_001.TestAlarm001", target.AlarmFullReference);
}
/// <summary>Verifies the canonical full reference omits the area segment when neither a discovered nor a configured area is present.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ResolveAsync_ComposesCanonicalFullReference_WithoutArea()
{
@@ -153,6 +167,8 @@ public sealed class AlarmWatchListResolverTests
Assert.Equal("Galaxy!Tank01.Level.HiHi", target.AlarmFullReference);
}
/// <summary>Verifies a config include entry with no discovered area falls back to the configured Discovery.Area.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ResolveAsync_ConfigInclude_UsesDiscoveryAreaFallback()
{
@@ -170,6 +186,8 @@ public sealed class AlarmWatchListResolverTests
Assert.Equal("Galaxy!Site_A.Tank01.Level.HiHi", target.AlarmFullReference);
}
/// <summary>Verifies a config include entry falls back to DefaultArea when Discovery.Area is empty.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ResolveAsync_ConfigInclude_FallsBackToDefaultArea_WhenDiscoveryAreaEmpty()
{
@@ -187,6 +205,8 @@ public sealed class AlarmWatchListResolverTests
Assert.Equal("Galaxy!Plant.Tank01.Level.HiHi", target.AlarmFullReference);
}
/// <summary>Verifies that disabling Galaxy Repository discovery skips the repository call and resolves the watch list from configured includes only.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ResolveAsync_UseGalaxyRepositoryFalse_DoesNotCallRepository_UsesIncludesOnly()
{
@@ -206,6 +226,8 @@ public sealed class AlarmWatchListResolverTests
Assert.Equal("Galaxy!Tank01.Level.HiHi", target.AlarmFullReference);
}
/// <summary>Verifies that a repository exception during discovery is logged and swallowed, returning the config-only watch list instead of throwing.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ResolveAsync_RepositoryThrows_LogsAndReturnsConfigOnlySet()
{
@@ -221,6 +243,8 @@ public sealed class AlarmWatchListResolverTests
Assert.Equal("Galaxy!Tank01.Level.HiHi", target.AlarmFullReference);
}
/// <summary>Verifies the source object reference is derived from a config include entry, using the portion before the first dot when present.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ResolveAsync_DerivesSourceObjectForConfigEntry()
{
@@ -240,6 +264,7 @@ public sealed class AlarmWatchListResolverTests
/// Fix 1: ExcludeAttributes must be ignored when UseGalaxyRepository is false.
/// A config-only include must survive even when the same path appears in ExcludeAttributes.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ResolveAsync_ExcludeIgnored_WhenGalaxyRepositoryDisabled()
{
@@ -262,6 +287,7 @@ public sealed class AlarmWatchListResolverTests
/// Fix 1 (GR-on path): ExcludeAttributes still prunes GR rows when
/// UseGalaxyRepository is true.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ResolveAsync_ExcludeApplied_WhenGalaxyRepositoryEnabled()
{
@@ -286,6 +312,7 @@ public sealed class AlarmWatchListResolverTests
/// Fix 1: A whitespace-only ExcludeAttributes entry must be skipped and must
/// not accidentally exclude any real reference.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ResolveAsync_WhitespaceOnlyExcludeEntry_IsSkipped()
{
@@ -307,11 +334,12 @@ public sealed class AlarmWatchListResolverTests
}
/// <summary>
/// Server-051: a cancellation triggered while Galaxy Repository discovery is
/// A cancellation triggered while Galaxy Repository discovery is
/// awaiting must propagate as <see cref="OperationCanceledException"/>, not be
/// swallowed into a config-only watch-list, per the <see cref="IAlarmWatchListResolver"/>
/// contract.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ResolveAsync_RepositoryCancelled_PropagatesOperationCanceled()
{
@@ -329,11 +357,12 @@ public sealed class AlarmWatchListResolverTests
}
/// <summary>
/// Server-052 item 2 / Server-053: an entry that appears in both
/// An entry that appears in both
/// <c>IncludeAttributes</c> and <c>ExcludeAttributes</c> is removed — excludes
/// win over explicit includes (the documented "excludes also suppress matching
/// explicit includes" behaviour).
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ResolveAsync_ExcludeAlsoSuppressesMatchingExplicitInclude()
{
@@ -362,22 +391,32 @@ public sealed class AlarmWatchListResolverTests
/// <summary>Gets the number of times <see cref="GetAlarmAttributesAsync"/> was called.</summary>
public int GetAlarmAttributesCount { get; private set; }
/// <inheritdoc />
/// <summary>Always reports a successful connection.</summary>
/// <param name="ct">Token to observe for cancellation.</param>
/// <returns>A completed task carrying <see langword="true"/>.</returns>
public Task<bool> TestConnectionAsync(CancellationToken ct = default) => Task.FromResult(true);
/// <inheritdoc />
/// <summary>Reports no known deploy time.</summary>
/// <param name="ct">Token to observe for cancellation.</param>
/// <returns>A completed task carrying <see langword="null"/>.</returns>
public Task<DateTime?> GetLastDeployTimeAsync(CancellationToken ct = default) =>
Task.FromResult<DateTime?>(null);
/// <inheritdoc />
/// <summary>Not exercised by these tests; returns an empty hierarchy.</summary>
/// <param name="ct">Token to observe for cancellation.</param>
/// <returns>A completed task carrying an empty list.</returns>
public Task<List<GalaxyHierarchyRow>> GetHierarchyAsync(CancellationToken ct = default) =>
Task.FromResult(new List<GalaxyHierarchyRow>());
/// <inheritdoc />
/// <summary>Not exercised by these tests; returns an empty attribute set.</summary>
/// <param name="ct">Token to observe for cancellation.</param>
/// <returns>A completed task carrying an empty list.</returns>
public Task<List<GalaxyAttributeRow>> GetAttributesAsync(CancellationToken ct = default) =>
Task.FromResult(new List<GalaxyAttributeRow>());
/// <inheritdoc />
/// <summary>Returns the fixed alarm rowset supplied at construction, tracking how many times it was called.</summary>
/// <param name="ct">Token to observe for cancellation.</param>
/// <returns>A completed task carrying the configured alarm attribute rows.</returns>
public Task<List<GalaxyAlarmAttributeRow>> GetAlarmAttributesAsync(CancellationToken ct = default)
{
GetAlarmAttributesCount++;
@@ -388,22 +427,32 @@ public sealed class AlarmWatchListResolverTests
/// <summary><see cref="IGalaxyRepository"/> whose alarm-attribute query throws.</summary>
private sealed class ThrowingGalaxyRepository(Exception toThrow) : IGalaxyRepository
{
/// <inheritdoc />
/// <summary>Always reports a successful connection; only alarm-attribute discovery fails for this fake.</summary>
/// <param name="ct">Token to observe for cancellation.</param>
/// <returns>A completed task carrying <see langword="true"/>.</returns>
public Task<bool> TestConnectionAsync(CancellationToken ct = default) => Task.FromResult(true);
/// <inheritdoc />
/// <summary>Reports no known deploy time.</summary>
/// <param name="ct">Token to observe for cancellation.</param>
/// <returns>A completed task carrying <see langword="null"/>.</returns>
public Task<DateTime?> GetLastDeployTimeAsync(CancellationToken ct = default) =>
Task.FromResult<DateTime?>(null);
/// <inheritdoc />
/// <summary>Not exercised by these tests; returns an empty hierarchy.</summary>
/// <param name="ct">Token to observe for cancellation.</param>
/// <returns>A completed task carrying an empty list.</returns>
public Task<List<GalaxyHierarchyRow>> GetHierarchyAsync(CancellationToken ct = default) =>
Task.FromResult(new List<GalaxyHierarchyRow>());
/// <inheritdoc />
/// <summary>Not exercised by these tests; returns an empty attribute set.</summary>
/// <param name="ct">Token to observe for cancellation.</param>
/// <returns>A completed task carrying an empty list.</returns>
public Task<List<GalaxyAttributeRow>> GetAttributesAsync(CancellationToken ct = default) =>
Task.FromResult(new List<GalaxyAttributeRow>());
/// <inheritdoc />
/// <summary>Simulates the live SQL path failing by faulting with the configured exception.</summary>
/// <param name="ct">Token to observe for cancellation.</param>
/// <returns>A faulted task carrying the configured exception.</returns>
public Task<List<GalaxyAlarmAttributeRow>> GetAlarmAttributesAsync(CancellationToken ct = default) =>
Task.FromException<List<GalaxyAlarmAttributeRow>>(toThrow);
}
@@ -415,22 +464,32 @@ public sealed class AlarmWatchListResolverTests
/// </summary>
private sealed class CancellingGalaxyRepository(CancellationTokenSource source) : IGalaxyRepository
{
/// <inheritdoc />
/// <summary>Always reports a successful connection; only alarm-attribute discovery cancels for this fake.</summary>
/// <param name="ct">Token to observe for cancellation.</param>
/// <returns>A completed task carrying <see langword="true"/>.</returns>
public Task<bool> TestConnectionAsync(CancellationToken ct = default) => Task.FromResult(true);
/// <inheritdoc />
/// <summary>Reports no known deploy time.</summary>
/// <param name="ct">Token to observe for cancellation.</param>
/// <returns>A completed task carrying <see langword="null"/>.</returns>
public Task<DateTime?> GetLastDeployTimeAsync(CancellationToken ct = default) =>
Task.FromResult<DateTime?>(null);
/// <inheritdoc />
/// <summary>Not exercised by these tests; returns an empty hierarchy.</summary>
/// <param name="ct">Token to observe for cancellation.</param>
/// <returns>A completed task carrying an empty list.</returns>
public Task<List<GalaxyHierarchyRow>> GetHierarchyAsync(CancellationToken ct = default) =>
Task.FromResult(new List<GalaxyHierarchyRow>());
/// <inheritdoc />
/// <summary>Not exercised by these tests; returns an empty attribute set.</summary>
/// <param name="ct">Token to observe for cancellation.</param>
/// <returns>A completed task carrying an empty list.</returns>
public Task<List<GalaxyAttributeRow>> GetAttributesAsync(CancellationToken ct = default) =>
Task.FromResult(new List<GalaxyAttributeRow>());
/// <inheritdoc />
/// <summary>Cancels the supplied source and throws, mirroring the live SQL path being cancelled mid-await.</summary>
/// <param name="ct">Token to observe for cancellation.</param>
/// <returns>Never returns normally; always throws <see cref="OperationCanceledException"/>.</returns>
public Task<List<GalaxyAlarmAttributeRow>> GetAlarmAttributesAsync(CancellationToken ct = default)
{
source.Cancel();
src/ZB.MOM.WW.MxGateway.Tests/Alarms/GatewayAlarmMonitorProviderModeTests.cs
+21 -2
View File
@@ -24,6 +24,8 @@ public sealed class GatewayAlarmMonitorProviderModeTests
{
private static readonly TimeSpan WaitTimeout = TimeSpan.FromSeconds(15);
/// <summary>A worker-reported provider-mode change to subtag broadcasts a degraded status message and increments the provider-switch metric.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ProviderModeChange_BroadcastsDegradedStatus_AndIncrementsSwitchMetric()
{
@@ -121,12 +123,13 @@ public sealed class GatewayAlarmMonitorProviderModeTests
}
/// <summary>
/// Server-053: a redundant <c>OnAlarmProviderModeChanged</c> event whose target
/// A redundant <c>OnAlarmProviderModeChanged</c> event whose target
/// mode equals the current mode still records a provider switch. The worker is the
/// authority on when a mode change occurred; the gateway does not second-guess it,
/// so each event the worker emits increments <c>provider_switches</c> (no from==to
/// suppression). This test pins that semantics so it cannot drift silently.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ProviderModeChange_RepeatedSameMode_RecordsASwitchForEachEvent()
{
@@ -219,7 +222,7 @@ public sealed class GatewayAlarmMonitorProviderModeTests
}
/// <summary>
/// Tests-032: pins the monitor's <c>toMode → AlarmProviderSwitchReason</c>
/// Pins the monitor's <c>toMode → AlarmProviderSwitchReason</c>
/// derivation (<c>GatewayAlarmMonitor.ApplyProviderModeChangeAsync</c>): an
/// alarmmgr→subtag change must emit <c>reason=failover</c> and a subtag→alarmmgr
/// change must emit <c>reason=failback</c>. Captures the <c>reason</c> tag off the
@@ -227,6 +230,7 @@ public sealed class GatewayAlarmMonitorProviderModeTests
/// the Failover/Failback arms or collapsed them to Unknown would be caught here,
/// whereas the count-only tests above would still pass.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ProviderModeChange_FailoverThenFailback_RecordsCorrectReasonTags()
{
@@ -338,6 +342,8 @@ public sealed class GatewayAlarmMonitorProviderModeTests
await monitor.StopAsync(CancellationToken.None);
}
/// <summary>A subscriber that joins the alarm feed receives the current provider status as its first message.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task NewSubscriber_ReceivesProviderStatusAsFirstMessage()
{
@@ -374,6 +380,8 @@ public sealed class GatewayAlarmMonitorProviderModeTests
await monitor.StopAsync(CancellationToken.None);
}
/// <summary>With the fallback mode forced to subtag, the initial provider status baselines to degraded subtag without recording a provider switch.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ForceSubtagConfig_BaselinesProviderStatusToSubtagDegraded_WithoutSwitch()
{
@@ -448,6 +456,8 @@ public sealed class GatewayAlarmMonitorProviderModeTests
await monitor.StopAsync(CancellationToken.None);
}
/// <summary>With the fallback mode forced to alarm manager, the initial provider status baselines to non-degraded alarmmgr without recording a provider switch.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ForceAlarmManagerConfig_BaselinesProviderStatusToAlarmmgr_WithoutSwitch()
{
@@ -519,6 +529,8 @@ public sealed class GatewayAlarmMonitorProviderModeTests
await monitor.StopAsync(CancellationToken.None);
}
/// <summary>The monitor's SubscribeAlarms command carries the forced provider mode, failover settings, and watch list resolved from configuration.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task SubscribeAlarms_SendsForcedModeAndWatchList_FromConfiguration()
{
@@ -565,6 +577,10 @@ public sealed class GatewayAlarmMonitorProviderModeTests
await monitor.StopAsync(CancellationToken.None);
}
/// <summary>The configured fallback mode string maps to the expected <see cref="AlarmProviderMode"/> sent in the SubscribeAlarms command.</summary>
/// <param name="mode">The configured fallback mode string.</param>
/// <param name="expected">The expected forced <see cref="AlarmProviderMode"/>.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
[Theory]
[InlineData("ForceAlarmManager", AlarmProviderMode.Alarmmgr)]
[InlineData("forcealarmmanager", AlarmProviderMode.Alarmmgr)]
@@ -701,10 +717,13 @@ public sealed class GatewayAlarmMonitorProviderModeTests
public SubscribeAlarmsCommand? LastSubscribeCommand { get; private set; }
/// <summary>Pushes a worker event onto the monitor's event stream.</summary>
/// <param name="mxEvent">The worker event to push.</param>
public void EmitEvent(MxEvent mxEvent) =>
_events.Writer.TryWrite(new WorkerEvent { Event = mxEvent });
/// <summary>Completes once the monitor has issued its SubscribeAlarms command.</summary>
/// <param name="timeout">The maximum time to wait.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
public Task WaitForSubscribeAsync(TimeSpan timeout) => _subscribed.Task.WaitAsync(timeout);
/// <inheritdoc />