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
@@ -17,15 +17,6 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
private readonly IMxAccessEventSink eventSink;
private readonly MxAccessEventQueue eventQueue;
private readonly StaRuntime staRuntime;
// Worker-024: the factory takes an Action so MxAccessStaSession can hand
// the alarm handler its STA-affinity guard (a closure over
// alarmConsumerThreadId captured at the factory call site). The handler
// then invokes the guard at the entry of every method that touches the
// wnwrap consumer, matching the STA-affinity invariant already enforced
// for the poll path via EnsureOnAlarmConsumerThread.
// Worker-9: the third arg is the session's IMxAccessComObjectFactory, so
// the handler can build the subtag-fallback source's own proxy-server COM
// object on this STA when a subscribe selects the subtag / failover path.
private readonly Func<MxAccessEventQueue, Action, IMxAccessComObjectFactory, IAlarmCommandHandler>? alarmCommandHandlerFactory;
private StaCommandDispatcher? commandDispatcher;
private MxAccessSession? session;
@@ -171,13 +162,7 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
return StartAsync(string.Empty, workerProcessId, cancellationToken);
}
/// <summary>
/// Starts the MXAccess COM session with a session ID asynchronously.
/// </summary>
/// <param name="sessionId">Session identifier.</param>
/// <param name="workerProcessId">Worker process identifier.</param>
/// <param name="cancellationToken">Cancellation token.</param>
/// <returns>Worker ready message.</returns>
/// <inheritdoc />
public async Task<WorkerReady> StartAsync(
string sessionId,
int workerProcessId,
@@ -204,20 +189,6 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
// thread id; RunAlarmPollLoopAsync then asserts each
// PollOnce executes on the same thread.
alarmConsumerThreadId = Environment.CurrentManagedThreadId;
// Worker-024: hand the handler an affinity guard so each
// of its command-path entries (Subscribe / Acknowledge /
// AcknowledgeByName / QueryActive / Unsubscribe / PollOnce)
// asserts the same STA-affinity invariant the poll path
// already enforced. Without this the command path relied
// on convention alone; a future refactor that let a
// command run off-STA would silently deadlock on
// cross-apartment marshaling against the wnwrap consumer.
// Worker-9: the factory also receives the session's
// IMxAccessComObjectFactory so the subtag-fallback source
// (LmxSubtagAlarmSource) can create its OWN proxy-server COM
// object on this STA, isolated from the item pipeline's
// MxAccessSession. The factory call runs on the STA, so the
// resulting source is bound to the correct apartment.
alarmCommandHandler = alarmCommandHandlerFactory(
eventQueue,
EnsureOnAlarmConsumerThread,
@@ -295,7 +266,7 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
// STA runtime shutting down — stop the loop gracefully.
// The dedicated shutdown type lets us distinguish this
// graceful-stop signal from the STA-affinity assertion
// raised by EnsureOnAlarmConsumerThread (Worker-008),
// raised by EnsureOnAlarmConsumerThread,
// which is also an InvalidOperationException but signals
// a programming-error regression — that case falls through
// to the generic Exception arm below and is recorded as a
@@ -378,11 +349,7 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
return fault;
}
/// <summary>
/// Dispatches a command to the STA thread for execution asynchronously.
/// </summary>
/// <param name="command">The command to dispatch.</param>
/// <returns>Command reply.</returns>
/// <inheritdoc />
public Task<MxCommandReply> DispatchAsync(StaCommand command)
{
if (commandDispatcher is null)
@@ -393,10 +360,7 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
return commandDispatcher.DispatchAsync(command);
}
/// <summary>
/// Captures a heartbeat snapshot of the session's runtime state.
/// </summary>
/// <returns>Heartbeat snapshot.</returns>
/// <inheritdoc />
public WorkerRuntimeHeartbeatSnapshot CaptureHeartbeat()
{
uint pendingCommandCount = 0;
@@ -416,38 +380,25 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
currentCommandCorrelationId);
}
/// <summary>
/// Requests graceful shutdown of the command dispatcher.
/// </summary>
/// <inheritdoc />
public void RequestShutdown()
{
commandDispatcher?.RequestShutdown();
}
/// <summary>
/// Drains up to the specified number of events from the queue.
/// </summary>
/// <param name="maxEvents">Maximum events to drain.</param>
/// <returns>Drained events.</returns>
/// <inheritdoc />
public IReadOnlyList<WorkerEvent> DrainEvents(uint maxEvents)
{
return eventQueue.Drain(maxEvents);
}
/// <summary>
/// Drains a fault from the queue if present.
/// </summary>
/// <returns>Drained fault or null.</returns>
/// <inheritdoc />
public WorkerFault? DrainFault()
{
return eventQueue.DrainFault();
}
/// <summary>
/// Cancels a queued command by correlation ID.
/// </summary>
/// <param name="correlationId">Correlation ID of the command to cancel.</param>
/// <returns>True if cancelled; otherwise false.</returns>
/// <inheritdoc />
public bool CancelCommand(string correlationId)
{
return commandDispatcher?.CancelQueuedCommand(correlationId) ?? false;
@@ -507,12 +458,7 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
cancellationToken);
}
/// <summary>
/// Performs graceful shutdown of the MXAccess session within a timeout.
/// </summary>
/// <param name="timeout">Maximum time allowed for shutdown.</param>
/// <param name="cancellationToken">Cancellation token.</param>
/// <returns>Shutdown result with any cleanup failures.</returns>
/// <inheritdoc />
public async Task<MxAccessShutdownResult> ShutdownGracefullyAsync(
TimeSpan timeout,
CancellationToken cancellationToken = default)
@@ -620,7 +566,7 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
return result;
}
/// <summary>Releases resources and shuts down the session.</summary>
/// <inheritdoc />
public void Dispose()
{
if (disposed)