Add XML documentation across gateway, worker, and .NET client

src/MxGateway.Worker/MxAccess/MxAccessStaSession.cs

@@ -18,6 +18,9 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
     private MxAccessSession? session;
     private bool disposed;
 
+    /// <summary>
+    /// Initializes a new instance of <see cref="MxAccessStaSession"/> with default dependencies.
+    /// </summary>
     public MxAccessStaSession()
         : this(
             new StaRuntime(),
@@ -26,6 +29,12 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of <see cref="MxAccessStaSession"/> with custom STA runtime and factory.
+    /// </summary>
+    /// <param name="staRuntime">STA thread runtime.</param>
+    /// <param name="factory">MXAccess COM object factory.</param>
+    /// <param name="eventSink">Event sink for MXAccess events.</param>
     public MxAccessStaSession(
         StaRuntime staRuntime,
         IMxAccessComObjectFactory factory,
@@ -34,6 +43,12 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of <see cref="MxAccessStaSession"/> with custom event queue.
+    /// </summary>
+    /// <param name="staRuntime">STA thread runtime.</param>
+    /// <param name="factory">MXAccess COM object factory.</param>
+    /// <param name="eventQueue">Event queue for buffering MXAccess events.</param>
     public MxAccessStaSession(
         StaRuntime staRuntime,
         IMxAccessComObjectFactory factory,
@@ -42,6 +57,13 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of <see cref="MxAccessStaSession"/> with all dependencies.
+    /// </summary>
+    /// <param name="staRuntime">STA thread runtime.</param>
+    /// <param name="factory">MXAccess COM object factory.</param>
+    /// <param name="eventSink">Event sink for MXAccess events.</param>
+    /// <param name="eventQueue">Event queue for buffering MXAccess events.</param>
     public MxAccessStaSession(
         StaRuntime staRuntime,
         IMxAccessComObjectFactory factory,
@@ -54,8 +76,17 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
         this.eventQueue = eventQueue ?? throw new ArgumentNullException(nameof(eventQueue));
     }
 
+    /// <summary>
+    /// Gets the event queue for this session.
+    /// </summary>
     public MxAccessEventQueue EventQueue => eventQueue;
 
+    /// <summary>
+    /// Starts the MXAccess COM session asynchronously.
+    /// </summary>
+    /// <param name="workerProcessId">Worker process identifier.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Worker ready message.</returns>
     public Task<WorkerReady> StartAsync(
         int workerProcessId,
         CancellationToken cancellationToken = default)
@@ -63,6 +94,13 @@ 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>
     public Task<WorkerReady> StartAsync(
         string sessionId,
         int workerProcessId,
@@ -88,6 +126,11 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
             cancellationToken);
     }
 
+    /// <summary>
+    /// Dispatches a command to the STA thread for execution asynchronously.
+    /// </summary>
+    /// <param name="command">The command to dispatch.</param>
+    /// <returns>Command reply.</returns>
     public Task<MxCommandReply> DispatchAsync(StaCommand command)
     {
         if (commandDispatcher is null)
@@ -98,6 +141,10 @@ 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>
     public WorkerRuntimeHeartbeatSnapshot CaptureHeartbeat()
     {
         uint pendingCommandCount = 0;
@@ -117,26 +164,48 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
             currentCommandCorrelationId);
     }
 
+    /// <summary>
+    /// Requests graceful shutdown of the command dispatcher.
+    /// </summary>
     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>
     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>
     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>
     public bool CancelCommand(string correlationId)
     {
         return commandDispatcher?.CancelQueuedCommand(correlationId) ?? false;
     }
 
+    /// <summary>
+    /// Gets the registered server handles asynchronously.
+    /// </summary>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Registered server handles.</returns>
     public Task<IReadOnlyList<RegisteredServerHandle>> GetRegisteredServerHandlesAsync(
         CancellationToken cancellationToken = default)
     {
@@ -150,6 +219,11 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
             cancellationToken);
     }
 
+    /// <summary>
+    /// Gets the registered item handles asynchronously.
+    /// </summary>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Registered item handles.</returns>
     public Task<IReadOnlyList<RegisteredItemHandle>> GetRegisteredItemHandlesAsync(
         CancellationToken cancellationToken = default)
     {
@@ -163,6 +237,11 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
             cancellationToken);
     }
 
+    /// <summary>
+    /// Gets the registered advice handles asynchronously.
+    /// </summary>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Registered advice handles.</returns>
     public Task<IReadOnlyList<RegisteredAdviceHandle>> GetRegisteredAdviceHandlesAsync(
         CancellationToken cancellationToken = default)
     {
@@ -176,6 +255,12 @@ 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>
     public async Task<MxAccessShutdownResult> ShutdownGracefullyAsync(
         TimeSpan timeout,
         CancellationToken cancellationToken = default)
@@ -238,6 +323,7 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
         return result;
     }
 
+    /// <summary>Releases resources and shuts down the session.</summary>
     public void Dispose()
     {
         if (disposed)