dohertj2/mxaccessgw
1
0
Fork 0
Code Issues 14 Pull Requests 2 Actions 4 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/MxAccessStaSessionTests.cs
+22 -38
View File
@@ -18,6 +18,7 @@ public sealed class MxAccessStaSessionTests
/// <summary>
/// Verifies that StartAsync creates the MXAccess COM object and attaches the event sink on the STA thread.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task StartAsync_CreatesComObjectAndAttachesEventSinkOnStaThread()
{
@@ -42,6 +43,7 @@ public sealed class MxAccessStaSessionTests
/// <summary>
/// Verifies that StartAsync maps creation exceptions with HResult when the factory fails.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task StartAsync_WhenFactoryFails_MapsCreationExceptionWithHResult()
{
@@ -63,6 +65,7 @@ public sealed class MxAccessStaSessionTests
/// <summary>
/// Verifies that Dispose detaches the event sink on the STA thread.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Dispose_DetachesEventSinkOnStaThread()
{
@@ -116,9 +119,7 @@ public sealed class MxAccessStaSessionTests
/// </summary>
public ApartmentState? CreateApartmentState { get; private set; }
/// <summary>
/// Creates the COM object or throws the configured exception.
/// </summary>
/// <inheritdoc />
public object Create()
{
CreateThreadId = Thread.CurrentThread.ManagedThreadId;
@@ -158,11 +159,7 @@ public sealed class MxAccessStaSessionTests
/// </summary>
public string? SessionId { get; private set; }
/// <summary>
/// Attaches the MXAccess COM object and records thread context.
/// </summary>
/// <param name="mxAccessComObject">MXAccess COM object to attach.</param>
/// <param name="sessionId">Identifier of the session.</param>
/// <inheritdoc />
public void Attach(
object mxAccessComObject,
string sessionId)
@@ -172,9 +169,7 @@ public sealed class MxAccessStaSessionTests
SessionId = sessionId;
}
/// <summary>
/// Detaches the MXAccess COM object and records thread context.
/// </summary>
/// <inheritdoc />
public void Detach()
{
DetachThreadId = Thread.CurrentThread.ManagedThreadId;
@@ -188,6 +183,7 @@ public sealed class MxAccessStaSessionTests
/// This proves the fix in WorkerPipeSession (and the new internal constructor) correctly
/// wires the factory rather than leaving alarmCommandHandler null.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task StartAsync_WithAlarmCommandHandlerFactory_SubscribeAlarmsCommandReachesHandler()
{
@@ -231,6 +227,7 @@ public sealed class MxAccessStaSessionTests
/// test fails if the diagnostic regresses to a misleading message that still
/// happens to contain the word "alarm".
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task StartAsync_WithoutAlarmCommandHandlerFactory_SubscribeAlarmsReturnsInvalidRequest()
{
@@ -267,6 +264,7 @@ public sealed class MxAccessStaSessionTests
/// loop calls PollOnce on the handler via the STA within a reasonable timeout.
/// This proves polling is driven by the STA rather than the consumer's internal timer.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task StartAsync_WithAlarmCommandHandlerFactory_PollOnceCalledViaSta()
{
@@ -304,6 +302,7 @@ public sealed class MxAccessStaSessionTests
/// immediately after Dispose and stays frozen — deterministic, with no
/// elapsed-time "no further polls" window that a slow agent could race.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Dispose_StopsAlarmPollLoop()
{
@@ -346,12 +345,13 @@ public sealed class MxAccessStaSessionTests
}
/// <summary>
/// Worker-005 regression: when the alarm poll loop's PollOnce throws a
/// When the alarm poll loop's PollOnce throws a
/// real failure (e.g. a COMException from GetXmlCurrentAlarms2), the
/// failure must be recorded as a fault on the event queue so a broken
/// alarm subscription becomes observable on the IPC fault path instead
/// of silently faulting the never-awaited poll task.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task RunAlarmPollLoop_WhenPollOnceThrows_RecordsFaultOnEventQueue()
{
@@ -389,7 +389,7 @@ public sealed class MxAccessStaSessionTests
}
/// <summary>
/// Worker-016 regression: the alarm poll loop's catch for the graceful
/// The alarm poll loop's catch for the graceful
/// STA-runtime-shutdown signal must NOT also swallow a vanilla
/// <see cref="InvalidOperationException"/> raised from inside the marshalled
/// poll lambda — for example the STA-affinity assertion thrown by
@@ -399,6 +399,7 @@ public sealed class MxAccessStaSessionTests
/// <see cref="InvalidOperationException"/> from <c>PollOnce</c> must reach
/// the fault-recording arm and become observable on the event queue.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task RunAlarmPollLoop_WhenPollOnceThrowsInvalidOperation_RecordsFaultOnEventQueue()
{
@@ -438,7 +439,7 @@ public sealed class MxAccessStaSessionTests
}
/// <summary>
/// Worker-008 regression: the STA-affinity guard throws when an
/// The STA-affinity guard throws when an
/// IMxAccessAlarmConsumer call is attempted off the thread that created
/// the consumer, mirroring the MxAccessSession.CreationThreadId invariant.
/// </summary>
@@ -455,7 +456,7 @@ public sealed class MxAccessStaSessionTests
}
/// <summary>
/// Worker-008: the STA-affinity guard is a no-op on the owning thread and
/// The STA-affinity guard is a no-op on the owning thread and
/// when no alarm consumer is configured (expected thread id null).
/// </summary>
[Fact]
@@ -495,52 +496,35 @@ public sealed class MxAccessStaSessionTests
get { lock (gate) return lastPollThreadId; }
}
/// <summary>Subscribes to alarm events.</summary>
/// <param name="command">The subscribe-alarms command.</param>
/// <param name="sessionId">The session identifier.</param>
/// <inheritdoc />
public void Subscribe(SubscribeAlarmsCommand command, string sessionId)
{
IsSubscribed = true;
LastSubscription = command.SubscriptionExpression;
}
/// <summary>Unsubscribes from alarm events.</summary>
/// <inheritdoc />
public void Unsubscribe()
{
IsSubscribed = false;
}
/// <summary>Acknowledges an alarm by guid.</summary>
/// <param name="alarmGuid">The alarm GUID.</param>
/// <param name="comment">The acknowledgment comment.</param>
/// <param name="operatorUser">The operator user name.</param>
/// <param name="operatorNode">The operator node name.</param>
/// <param name="operatorDomain">The operator domain.</param>
/// <param name="operatorFullName">The operator full name.</param>
/// <inheritdoc />
public int Acknowledge(Guid alarmGuid, string comment, string operatorUser,
string operatorNode, string operatorDomain, string operatorFullName)
=> 0;
/// <summary>Acknowledges an alarm by name.</summary>
/// <param name="alarmName">The alarm name.</param>
/// <param name="providerName">The provider name.</param>
/// <param name="groupName">The alarm group name.</param>
/// <param name="comment">The acknowledgment comment.</param>
/// <param name="operatorUser">The operator user name.</param>
/// <param name="operatorNode">The operator node name.</param>
/// <param name="operatorDomain">The operator domain.</param>
/// <param name="operatorFullName">The operator full name.</param>
/// <inheritdoc />
public int AcknowledgeByName(string alarmName, string providerName, string groupName,
string comment, string operatorUser, string operatorNode,
string operatorDomain, string operatorFullName)
=> 0;
/// <summary>Queries active alarms.</summary>
/// <param name="alarmFilterPrefix">Optional alarm name filter prefix.</param>
/// <inheritdoc />
public IReadOnlyList<ActiveAlarmSnapshot> QueryActive(string? alarmFilterPrefix)
=> Array.Empty<ActiveAlarmSnapshot>();
/// <summary>Polls for alarm events once.</summary>
/// <inheritdoc />
public void PollOnce()
{
lock (gate)