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
@@ -10,6 +10,7 @@ public interface IWorkerPipeClient
/// <summary>Connects to the gateway and runs the worker until the session ends or is cancelled.</summary>
/// <param name="options">Configuration options.</param>
/// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
Task RunAsync(
WorkerOptions options,
CancellationToken cancellationToken = default);
@@ -27,6 +27,7 @@ public sealed class WorkerFrameReader
/// <summary>Reads and validates a single length-prefixed frame from the stream.</summary>
/// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
/// <returns>The validated <see cref="WorkerEnvelope"/> read from the stream.</returns>
public async Task<WorkerEnvelope> ReadAsync(CancellationToken cancellationToken = default)
{
byte[] lengthPrefix = new byte[sizeof(uint)];
@@ -28,6 +28,7 @@ public sealed class WorkerFrameWriter
/// <summary>Writes a worker envelope frame to the stream with length prefix.</summary>
/// <param name="envelope">Worker envelope to write.</param>
/// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
public async Task WriteAsync(
WorkerEnvelope envelope,
CancellationToken cancellationToken = default)
@@ -139,11 +139,7 @@ public sealed class WorkerPipeClient : IWorkerPipeClient
_connectAttemptTimeoutMilliseconds = connectAttemptTimeoutMilliseconds;
}
/// <summary>
/// Runs the worker by connecting to the gateway and executing the frame protocol.
/// </summary>
/// <param name="options">Worker configuration options.</param>
/// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
/// <inheritdoc />
public async Task RunAsync(
WorkerOptions options,
CancellationToken cancellationToken = default)
@@ -106,15 +106,9 @@ public sealed class WorkerPipeSession
/// <summary>Runs the worker session, completing the handshake and processing messages until cancellation.</summary>
/// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
public async Task RunAsync(CancellationToken cancellationToken = default)
{
// Worker-025: the factory delegate itself is null-checked in the
// constructor, but its return value is not — a factory that returned
// null would NRE on the StartAsync lambda below. Throw a diagnostic
// exception instead so the failure is unambiguous (and so the
// finally block's _runtimeSession?.Dispose() can't silently no-op
// on a torn half-initialized session). Mirrors the same pattern
// AlarmCommandHandler.Subscribe uses for its consumerFactory().
_runtimeSession = _runtimeSessionFactory()
?? throw new InvalidOperationException(
"Worker runtime session factory returned null.");
@@ -142,6 +136,7 @@ public sealed class WorkerPipeSession
/// <summary>Completes the gateway startup handshake using default MXAccess initialization.</summary>
/// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
public Task CompleteStartupHandshakeAsync(CancellationToken cancellationToken = default)
{
return CompleteStartupHandshakeAsync(InitializeMxAccessAsync, cancellationToken);
@@ -150,6 +145,7 @@ public sealed class WorkerPipeSession
/// <summary>Completes the gateway startup handshake with custom MXAccess initialization that returns void.</summary>
/// <param name="initializeMxAccessAsync">Async function to initialize MXAccess.</param>
/// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
public async Task CompleteStartupHandshakeAsync(
Func<CancellationToken, Task> initializeMxAccessAsync,
CancellationToken cancellationToken = default)
@@ -171,6 +167,7 @@ public sealed class WorkerPipeSession
/// <summary>Completes the gateway startup handshake with custom MXAccess initialization that returns WorkerReady.</summary>
/// <param name="initializeMxAccessAsync">Async function to initialize MXAccess and return ready state.</param>
/// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
public async Task CompleteStartupHandshakeAsync(
Func<CancellationToken, Task<WorkerReady>> initializeMxAccessAsync,
CancellationToken cancellationToken = default)
@@ -811,7 +808,7 @@ public sealed class WorkerPipeSession
/// command (e.g. <c>ReadBulk</c> waiting <c>timeout_ms</c> for the
/// first OnDataChange callback) freezes <c>LastActivityUtc</c> for the
/// duration of the wait even though the worker is healthy. To avoid
/// self-faulting a healthy in-flight command (Worker-017), the
/// self-faulting a healthy in-flight command, the
/// watchdog is suppressed while <c>CurrentCommandCorrelationId</c> is
/// non-empty — the worker already advertises the in-flight command on
/// each heartbeat, so the gateway has the signal it needs to decide
@@ -819,18 +816,6 @@ public sealed class WorkerPipeSession
/// STA (no command in flight and no activity), which is the only case
/// the watchdog can usefully distinguish from a slow command.
/// </summary>
/// <remarks>
/// Worker-023: the in-flight-command suppression is itself bounded by
/// <c>WorkerPipeSessionOptions.HeartbeatStuckCeiling</c>. A truly stuck
/// synchronous COM call (e.g. against a dead MXAccess provider whose
/// cross-apartment marshaler is permanently blocked) leaves
/// <c>CurrentCommandCorrelationId</c> non-empty forever; without an
/// upper bound the worker-side <c>StaHung</c> watchdog would be
/// permanently defeated and only the gateway's per-command timeout
/// would catch the hang. Once <c>LastActivityUtc</c> has been stale
/// for longer than <c>HeartbeatStuckCeiling</c> the watchdog fires
/// <c>StaHung</c> regardless of whether a command is in flight.
/// </remarks>
private async Task ReportWatchdogFaultIfNeededAsync(
WorkerRuntimeHeartbeatSnapshot snapshot,
CancellationToken cancellationToken)
@@ -852,12 +837,6 @@ public sealed class WorkerPipeSession
// point this branch stops being taken. The heartbeat already
// surfaces the in-flight correlation id so the gateway can apply
// its own per-command timeout if it considers the command too slow.
//
// Worker-023: once staleFor exceeds HeartbeatStuckCeiling we fall
// through to the fault path even with a command in flight — a
// truly stuck synchronous COM call would otherwise keep
// CurrentCommandCorrelationId non-empty indefinitely and the
// worker-side watchdog would never fire.
return;
}
@@ -35,7 +35,7 @@ public sealed class WorkerPipeSessionOptions
/// <summary>
/// Gets or sets the defensive upper bound on how long the watchdog
/// will suppress its <c>StaHung</c> fault while a command is in
/// flight. Worker-017 suppresses the watchdog when the heartbeat
/// flight. The watchdog suppresses itself when the heartbeat
/// snapshot's <c>CurrentCommandCorrelationId</c> is non-empty so a
/// legitimately slow command (e.g. <c>ReadBulk</c> against many
/// uncached tags) does not self-fault — but a truly stuck