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

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
@@ -18,6 +18,7 @@ namespace ZB.MOM.WW.MxGateway.Tests.Gateway.Grpc;
public sealed class MxAccessGatewayServiceTests
{
/// <summary>Verifies that OpenSession returns correct session details for a valid request.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task OpenSession_WithValidRequest_ReturnsSessionDetails()
{
@@ -56,6 +57,7 @@ public sealed class MxAccessGatewayServiceTests
/// <c>TryGetSession</c> return false, so this test fails if the service drops
/// its missing-session check rather than passing for the wrong reason.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Invoke_WhenSessionMissing_ThrowsNotFound()
{
@@ -78,6 +80,7 @@ public sealed class MxAccessGatewayServiceTests
/// manager when <see cref="FakeSessionManager.ResolveOnlySeededSessions"/> is on,
/// confirming the missing-session test above is gated on a real lookup.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Invoke_WhenSessionSeeded_ResolvesAndInvokes()
{
@@ -94,6 +97,7 @@ public sealed class MxAccessGatewayServiceTests
}
/// <summary>Verifies that Invoke throws InvalidArgument and does not invoke the session manager when payload is mismatched.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Invoke_WithMismatchedPayload_ThrowsInvalidArgumentAndDoesNotCallSessionManager()
{
@@ -117,6 +121,7 @@ public sealed class MxAccessGatewayServiceTests
}
/// <summary>Verifies that Invoke returns HResult status and method payload from worker reply.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Invoke_WithWorkerReply_ReturnsHresultStatusAndMethodPayload()
{
@@ -172,6 +177,7 @@ public sealed class MxAccessGatewayServiceTests
}
/// <summary>Verifies that StreamEvents writes only events after the specified worker sequence.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task StreamEvents_WithAfterSequence_WritesOnlyLaterEvents()
{
@@ -197,15 +203,8 @@ public sealed class MxAccessGatewayServiceTests
/// <summary>
/// Verifies that <c>StreamEvents</c> records the send-duration histogram per event.
///
/// <para>Tests-027 (concurrency flake): the listener must filter by the specific
/// <see cref="System.Diagnostics.Metrics.Meter"/> instance owned by this test, not by the process-shared
/// <see cref="GatewayMetrics.MeterName"/>. Otherwise a parallel test that constructs its own
/// <see cref="GatewayMetrics"/> and records <c>mxgateway.events.stream_send.duration</c> would
/// cross-contaminate <c>families</c> and break the equality assertion below. See the companion
/// <see cref="StreamEvents_RecordSendDurationListener_IgnoresMeasurementsFromOtherMetersWithSameName"/>
/// regression for the cross-talk reproduction.</para>
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task StreamEvents_WhenEventIsWritten_RecordsSendDuration()
{
@@ -252,13 +251,14 @@ public sealed class MxAccessGatewayServiceTests
}
/// <summary>
/// Tests-027 regression: a <see cref="MeterListener"/> that filters by the specific
/// A <see cref="MeterListener"/> that filters by the specific
/// <see cref="System.Diagnostics.Metrics.Meter"/> instance (via <see cref="object.ReferenceEquals"/>)
/// must NOT observe measurements recorded on a different <see cref="GatewayMetrics"/> that shares
/// the same <see cref="GatewayMetrics.MeterName"/>. This is the cross-talk vector that previously
/// caused <c>StreamEvents_WhenEventIsWritten_RecordsSendDuration</c> to fail intermittently when
/// run in parallel with another test recording the same histogram.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task StreamEvents_RecordSendDurationListener_IgnoresMeasurementsFromOtherMetersWithSameName()
{
@@ -315,6 +315,7 @@ public sealed class MxAccessGatewayServiceTests
}
/// <summary>Verifies that CloseSession throws InvalidArgument when session ID is blank.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task CloseSession_WithBlankSessionId_ThrowsInvalidArgument()
{
@@ -335,6 +336,7 @@ public sealed class MxAccessGatewayServiceTests
// alarm feed. CreateService injects FakeGatewayAlarmService.
/// <summary>Verifies AcknowledgeAlarm rejects an empty alarm_full_reference.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task AcknowledgeAlarm_WithMissingAlarmReference_ThrowsInvalidArgument()
{
@@ -349,6 +351,7 @@ public sealed class MxAccessGatewayServiceTests
}
/// <summary>Verifies AcknowledgeAlarm delegates a valid request to the alarm service.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task AcknowledgeAlarm_WithValidRequest_DelegatesToAlarmService()
{
@@ -369,6 +372,7 @@ public sealed class MxAccessGatewayServiceTests
}
/// <summary>Verifies StreamAlarms forwards the central alarm feed, ending with snapshot_complete.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task StreamAlarms_ForwardsTheCentralAlarmFeed()
{
@@ -386,6 +390,7 @@ public sealed class MxAccessGatewayServiceTests
}
/// <summary>Verifies OpenSession advertises the alarm RPC capability strings.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task OpenSession_AdvertisesAlarmRpcCapabilities()
{
@@ -715,7 +720,8 @@ public sealed class MxAccessGatewayServiceTests
{
}
/// <inheritdoc />
/// <summary>Completes immediately without disposing any resources.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
public ValueTask DisposeAsync()
{
return ValueTask.CompletedTask;