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:
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user