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/Gateway/Dashboard/DashboardSnapshotPublisherTests.cs
+19 -21
View File
@@ -11,20 +11,14 @@ public sealed class DashboardSnapshotPublisherTests
private static readonly TimeSpan TestTimeout = TimeSpan.FromSeconds(5);
/// <summary>
/// Server-042 regression: a transient failure inside
/// A transient failure inside
/// <see cref="IDashboardSnapshotService.WatchSnapshotsAsync"/> must not
/// end the BackgroundService; the publisher must wait the configured
/// reconnect delay and then re-open the subscription. Before the fix,
/// the publisher exited on the first non-cancellation exception and
/// the dashboard's snapshot stream went silent until process restart.
///
/// <para>Tests-031: the reconnect-gap measurement is bounded between the
/// moment the first subscribe actually <c>throw</c>s and the moment the
/// second subscribe begins. Measuring from <c>startedAt</c> (pre-<c>StartAsync</c>)
/// baselined scheduling overhead into the budget and made the lower bound
/// flaky on slow CI; recording <c>firstThrowAt</c> inside the fake removes
/// that baseline so only the <c>Task.Delay(reconnectDelay)</c> contributes.</para>
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ExecuteAsync_WhenSnapshotServiceThrowsOnce_ReconnectsAfterDelay()
{
@@ -60,12 +54,6 @@ public sealed class DashboardSnapshotPublisherTests
$"Expected at least 2 subscribe calls, got {snapshotService.SubscribeCount}.");
Assert.True(hubContext.SendCount >= 1);
// Tests-031: the gap is measured from the moment the first subscribe
// actually threw (inside the fake) to the moment the second subscribe
// began (also inside the fake). This isolates the publisher's
// Task.Delay(reconnectDelay) — no StartAsync / scheduling overhead in
// the baseline. The 10ms slack absorbs Task.Delay's coarse Windows
// timer quantum (~15ms) when the underlying scheduler wakes early.
TimeSpan gap = secondSubscribeAt - firstThrowAt;
Assert.True(gap >= reconnectDelay - TimeSpan.FromMilliseconds(10),
$"Expected reconnect gap >= {reconnectDelay.TotalMilliseconds}ms; got {gap.TotalMilliseconds}ms.");
@@ -75,6 +63,7 @@ public sealed class DashboardSnapshotPublisherTests
/// Sanity: a normal completion of WatchSnapshotsAsync (no exception)
/// also reconnects after the delay — exits only on host shutdown.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ExecuteAsync_WhenSnapshotServiceCompletes_ReconnectsAfterDelay()
{
@@ -114,7 +103,7 @@ public sealed class DashboardSnapshotPublisherTests
public int SubscribeCount { get; private set; }
/// <summary>
/// Tests-031: the wall-clock instant the first <c>WatchSnapshotsAsync</c> throws.
/// The wall-clock instant the first <c>WatchSnapshotsAsync</c> throws.
/// The reconnect-gap assertion is measured against this timestamp (NOT the
/// pre-<c>StartAsync</c> wall clock) so scheduling overhead is not baselined
/// into the lower bound.
@@ -124,14 +113,13 @@ public sealed class DashboardSnapshotPublisherTests
/// <summary>Gets the wall-clock instant of the second subscription attempt.</summary>
public DateTimeOffset? SecondSubscribeAt { get; private set; }
/// <summary>Gets the current snapshot.</summary>
/// <inheritdoc />
public DashboardSnapshot GetSnapshot()
{
return null!;
}
/// <summary>Watches for snapshot changes and yields them asynchronously.</summary>
/// <param name="cancellationToken">Token to observe for cancellation.</param>
/// <inheritdoc />
public async IAsyncEnumerable<DashboardSnapshot> WatchSnapshotsAsync(
[EnumeratorCancellation] CancellationToken cancellationToken)
{
@@ -167,14 +155,13 @@ public sealed class DashboardSnapshotPublisherTests
/// <summary>Gets the number of subscription attempts.</summary>
public int SubscribeCount { get; private set; }
/// <summary>Gets the current snapshot.</summary>
/// <inheritdoc />
public DashboardSnapshot GetSnapshot()
{
return null!;
}
/// <summary>Watches for snapshot changes and completes immediately.</summary>
/// <param name="cancellationToken">Token to observe for cancellation.</param>
/// <inheritdoc />
#pragma warning disable CS1998 // async without await — IAsyncEnumerable contract requires async signature
public async IAsyncEnumerable<DashboardSnapshot> WatchSnapshotsAsync(
[EnumeratorCancellation] CancellationToken cancellationToken)
@@ -211,35 +198,43 @@ public sealed class DashboardSnapshotPublisherTests
/// <summary>Gets a client proxy excluding specified connections.</summary>
/// <param name="excludedConnectionIds">Connection identifiers to exclude.</param>
/// <returns>The recording client proxy shared by this fake.</returns>
public IClientProxy AllExcept(IReadOnlyList<string> excludedConnectionIds) => AllProxy;
/// <summary>Gets a client proxy for a specific connection.</summary>
/// <param name="connectionId">The connection identifier.</param>
/// <returns>The recording client proxy shared by this fake.</returns>
public IClientProxy Client(string connectionId) => AllProxy;
/// <summary>Gets a client proxy for specified connections.</summary>
/// <param name="connectionIds">The connection identifiers.</param>
/// <returns>The recording client proxy shared by this fake.</returns>
public IClientProxy Clients(IReadOnlyList<string> connectionIds) => AllProxy;
/// <summary>Gets a client proxy for a group.</summary>
/// <param name="groupName">The group name.</param>
/// <returns>The recording client proxy shared by this fake.</returns>
public IClientProxy Group(string groupName) => AllProxy;
/// <summary>Gets a client proxy for a group excluding specified connections.</summary>
/// <param name="groupName">The group name.</param>
/// <param name="excludedConnectionIds">Connection identifiers to exclude.</param>
/// <returns>The recording client proxy shared by this fake.</returns>
public IClientProxy GroupExcept(string groupName, IReadOnlyList<string> excludedConnectionIds) => AllProxy;
/// <summary>Gets a client proxy for specified groups.</summary>
/// <param name="groupNames">The group names.</param>
/// <returns>The recording client proxy shared by this fake.</returns>
public IClientProxy Groups(IReadOnlyList<string> groupNames) => AllProxy;
/// <summary>Gets a client proxy for a specific user.</summary>
/// <param name="userId">The user identifier.</param>
/// <returns>The recording client proxy shared by this fake.</returns>
public IClientProxy User(string userId) => AllProxy;
/// <summary>Gets a client proxy for specified users.</summary>
/// <param name="userIds">The user identifiers.</param>
/// <returns>The recording client proxy shared by this fake.</returns>
public IClientProxy Users(IReadOnlyList<string> userIds) => AllProxy;
}
@@ -254,6 +249,7 @@ public sealed class DashboardSnapshotPublisherTests
/// <param name="method">The SignalR method name.</param>
/// <param name="args">The method arguments.</param>
/// <param name="cancellationToken">Token to observe for cancellation.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
public Task SendCoreAsync(string method, object?[] args, CancellationToken cancellationToken = default)
{
Interlocked.Increment(ref _sendCount);
@@ -267,6 +263,7 @@ public sealed class DashboardSnapshotPublisherTests
/// <param name="connectionId">The connection identifier.</param>
/// <param name="groupName">The group name.</param>
/// <param name="cancellationToken">Token to observe for cancellation.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
public Task AddToGroupAsync(string connectionId, string groupName, CancellationToken cancellationToken = default)
=> Task.CompletedTask;
@@ -274,6 +271,7 @@ public sealed class DashboardSnapshotPublisherTests
/// <param name="connectionId">The connection identifier.</param>
/// <param name="groupName">The group name.</param>
/// <param name="cancellationToken">Token to observe for cancellation.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
public Task RemoveFromGroupAsync(string connectionId, string groupName, CancellationToken cancellationToken = default)
=> Task.CompletedTask;
}