docs: add missing XML doc comments across gateway, worker, and .NET client

Resolves 1113 documentation-completeness gaps flagged by CommentChecker
(MissingReturns, MissingInheritDoc, InheritDocMisused, MissingDoc,
MissingParam, RedundantInheritDoc) so the API surface is fully documented
and the analyzer scan is clean. Doc comments only; no code changes.

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/CliArguments.cs

@@ -44,6 +44,7 @@ internal sealed class CliArguments
 
     /// <summary>Returns whether the named flag was present in the arguments.</summary>
     /// <param name="name">The flag name (without '--' prefix).</param>
+    /// <returns>True if the flag was present; otherwise false.</returns>
     public bool HasFlag(string name)
     {
         return _flags.Contains(name);
@@ -51,6 +52,7 @@ internal sealed class CliArguments
 
     /// <summary>Returns the value for a named argument, or <c>null</c> if absent.</summary>
     /// <param name="name">The argument name (without '--' prefix).</param>
+    /// <returns>The argument value, or null if the argument was not provided.</returns>
     public string? GetOptional(string name)
     {
         return _values.TryGetValue(name, out string? value)
@@ -60,6 +62,7 @@ internal sealed class CliArguments
 
     /// <summary>Returns the value for a required named argument, or throws if absent.</summary>
     /// <param name="name">The argument name (without '--' prefix).</param>
+    /// <returns>The argument value.</returns>
     public string GetRequired(string name)
     {
         string? value = GetOptional(name);
@@ -74,6 +77,7 @@ internal sealed class CliArguments
     /// <summary>Parses and returns an int32 argument, or the default value if absent.</summary>
     /// <param name="name">The argument name (without '--' prefix).</param>
     /// <param name="defaultValue">The default value if the argument is absent; if <c>null</c>, the argument is required.</param>
+    /// <returns>The parsed int32 value, or the default if absent.</returns>
     public int GetInt32(string name, int? defaultValue = null)
     {
         string? value = GetOptional(name);
@@ -93,6 +97,7 @@ internal sealed class CliArguments
     /// <summary>Parses and returns a uint32 argument, or the default value if absent.</summary>
     /// <param name="name">The argument name (without '--' prefix).</param>
     /// <param name="defaultValue">The default value if the argument is absent.</param>
+    /// <returns>The parsed uint32 value, or the default if absent.</returns>
     public uint GetUInt32(string name, uint defaultValue)
     {
         string? value = GetOptional(name);
@@ -104,6 +109,7 @@ internal sealed class CliArguments
     /// <summary>Parses and returns a uint64 argument, or the default value if absent.</summary>
     /// <param name="name">The argument name (without '--' prefix).</param>
     /// <param name="defaultValue">The default value if the argument is absent.</param>
+    /// <returns>The parsed uint64 value, or the default if absent.</returns>
     public ulong GetUInt64(string name, ulong defaultValue)
     {
         string? value = GetOptional(name);
@@ -115,6 +121,7 @@ internal sealed class CliArguments
     /// <summary>Parses and returns a TimeSpan argument, or the default value if absent. Supports "ms", "s", and standard TimeSpan format.</summary>
     /// <param name="name">The argument name (without '--' prefix).</param>
     /// <param name="defaultValue">The default value if the argument is absent.</param>
+    /// <returns>The parsed TimeSpan value, or the default if absent.</returns>
     public TimeSpan GetDuration(string name, TimeSpan defaultValue)
     {
         string? value = GetOptional(name);

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/MxGatewayCliClientAdapter.cs

@@ -100,7 +100,8 @@ internal sealed class MxGatewayCliClientAdapter : IMxGatewayCliClient
         return _galaxyClient.Value.WatchDeployEventsRawAsync(request, cancellationToken);
     }
 
-    /// <inheritdoc />
+    /// <summary>Disposes the galaxy client (if created) and the underlying gateway client.</summary>
+    /// <returns>A value task that completes when both clients are disposed.</returns>
     public async ValueTask DisposeAsync()
     {
         if (_galaxyClient.IsValueCreated)

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/MxGatewayCliSecretRedactor.cs

@@ -6,6 +6,7 @@ internal static class MxGatewayCliSecretRedactor
     /// <summary>Replaces occurrences of the API key in the value with a redacted placeholder.</summary>
     /// <param name="value">The message text to redact.</param>
     /// <param name="apiKey">The API key to remove; no redaction if null or empty.</param>
+    /// <returns>The message text with any API key occurrence replaced by <c>[redacted]</c>.</returns>
     public static string Redact(string value, string? apiKey)
     {
         if (string.IsNullOrEmpty(value) || string.IsNullOrEmpty(apiKey))

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/MxGatewayClientCli.cs

@@ -22,6 +22,7 @@ public static class MxGatewayClientCli
     /// <param name="args">Command-line arguments (command name followed by options).</param>
     /// <param name="standardOutput">TextWriter for command output.</param>
     /// <param name="standardError">TextWriter for error messages.</param>
+    /// <returns>The process exit code (0 for success, 1 for error).</returns>
     public static int Run(
         string[] args,
         TextWriter standardOutput,
@@ -38,6 +39,7 @@ public static class MxGatewayClientCli
     /// <param name="standardError">TextWriter for error messages.</param>
     /// <param name="clientFactory">Optional factory to create the gateway client; defaults to MxGatewayClient.Create.</param>
     /// <param name="standardInput">Optional TextReader for batch-mode stdin; defaults to <see cref="Console.In"/>.</param>
+    /// <returns>A task that resolves to the process exit code (0 for success, 1 for error).</returns>
     public static Task<int> RunAsync(
         string[] args,
         TextWriter standardOutput,

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/BrowseChildrenSmokeTests.cs

@@ -14,6 +14,7 @@ public sealed class BrowseChildrenSmokeTests
     /// Verifies that BrowseChildren returns a non-zero cache sequence and
     /// a consistent children/child-has-children count from a live gateway.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact(Skip = "Set MXGATEWAY_API_KEY and MXGATEWAY_ENDPOINT to enable.")]
     public async Task BrowseChildren_LiveGateway_ReturnsRootsWithCacheSequence()
     {

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/FakeGalaxyRepositoryTransport.cs

@@ -8,14 +8,10 @@ namespace ZB.MOM.WW.MxGateway.Client.Tests;
 /// </summary>
 internal sealed class FakeGalaxyRepositoryTransport(MxGatewayClientOptions options) : IGalaxyRepositoryClientTransport
 {
-    /// <summary>
-    /// Gets the gateway client options.
-    /// </summary>
+    /// <inheritdoc />
     public MxGatewayClientOptions Options { get; } = options;
 
-    /// <summary>
-    /// Gets the raw gRPC client; always null for the fake.
-    /// </summary>
+    /// <inheritdoc />
     public GalaxyRepository.GalaxyRepositoryClient? RawClient => null;
 
     /// <summary>
@@ -66,11 +62,7 @@ internal sealed class FakeGalaxyRepositoryTransport(MxGatewayClientOptions optio
     /// </summary>
     public Queue<Exception> DiscoverHierarchyExceptions { get; } = new();
 
-    /// <summary>
-    /// Records the request and either throws a queued exception or returns the configured reply.
-    /// </summary>
-    /// <param name="request">The TestConnectionRequest to process.</param>
-    /// <param name="callOptions">Call options specifying RPC behavior.</param>
+    /// <inheritdoc />
     public Task<TestConnectionReply> TestConnectionAsync(
         TestConnectionRequest request,
         CallOptions callOptions)
@@ -84,11 +76,7 @@ internal sealed class FakeGalaxyRepositoryTransport(MxGatewayClientOptions optio
         return Task.FromResult(TestConnectionReply);
     }
 
-    /// <summary>
-    /// Records the request and either throws a queued exception or returns the configured reply.
-    /// </summary>
-    /// <param name="request">The GetLastDeployTimeRequest to process.</param>
-    /// <param name="callOptions">Call options specifying RPC behavior.</param>
+    /// <inheritdoc />
     public Task<GetLastDeployTimeReply> GetLastDeployTimeAsync(
         GetLastDeployTimeRequest request,
         CallOptions callOptions)
@@ -102,11 +90,7 @@ internal sealed class FakeGalaxyRepositoryTransport(MxGatewayClientOptions optio
         return Task.FromResult(GetLastDeployTimeReply);
     }
 
-    /// <summary>
-    /// Records the request and either throws a queued exception or returns the configured reply.
-    /// </summary>
-    /// <param name="request">The DiscoverHierarchyRequest to process.</param>
-    /// <param name="callOptions">Call options specifying RPC behavior.</param>
+    /// <inheritdoc />
     public Task<DiscoverHierarchyReply> DiscoverHierarchyAsync(
         DiscoverHierarchyRequest request,
         CallOptions callOptions)
@@ -135,11 +119,7 @@ internal sealed class FakeGalaxyRepositoryTransport(MxGatewayClientOptions optio
     /// <summary>Queue of exceptions to throw from BrowseChildren; dequeued in FIFO order.</summary>
     public Queue<Exception> BrowseChildrenExceptions { get; } = new();
 
-    /// <summary>
-    /// Records the request and either throws a queued exception or returns the configured reply.
-    /// </summary>
-    /// <param name="request">The BrowseChildrenRequest to process.</param>
-    /// <param name="callOptions">Call options specifying RPC behavior.</param>
+    /// <inheritdoc />
     public Task<BrowseChildrenReply> BrowseChildrenAsync(
         BrowseChildrenRequest request,
         CallOptions callOptions)
@@ -177,11 +157,7 @@ internal sealed class FakeGalaxyRepositoryTransport(MxGatewayClientOptions optio
     /// </summary>
     public Func<CancellationToken, Task>? WatchDeployEventsBeforeYield { get; set; }
 
-    /// <summary>
-    /// Records the request and streams events, checking for queued exceptions and calling WatchDeployEventsBeforeYield before each event.
-    /// </summary>
-    /// <param name="request">The WatchDeployEventsRequest to process.</param>
-    /// <param name="callOptions">Call options specifying RPC behavior.</param>
+    /// <inheritdoc />
     public async IAsyncEnumerable<DeployEvent> WatchDeployEventsAsync(
         WatchDeployEventsRequest request,
         CallOptions callOptions)

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/FakeGatewayTransport.cs

@@ -11,14 +11,10 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
     private readonly Queue<MxCommandReply> _invokeReplies = new();
     private readonly List<MxEvent> _events = [];
 
-    /// <summary>
-    /// Gets the gateway client options.
-    /// </summary>
+    /// <inheritdoc />
     public MxGatewayClientOptions Options { get; } = options;
 
-    /// <summary>
-    /// Gets null, since this is a test fake without a real gRPC client.
-    /// </summary>
+    /// <inheritdoc />
     public MxAccessGateway.MxAccessGatewayClient? RawClient => null;
 
     /// <summary>
@@ -102,11 +98,7 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
     /// </summary>
     public Queue<Exception> InvokeExceptions { get; } = new();
 
-    /// <summary>
-    /// Verifies that the OpenSessionAsync call is recorded and returns the configured reply.
-    /// </summary>
-    /// <param name="request">The OpenSessionRequest to process.</param>
-    /// <param name="callOptions">Call options specifying RPC behavior.</param>
+    /// <inheritdoc />
     public Task<OpenSessionReply> OpenSessionAsync(
         OpenSessionRequest request,
         CallOptions callOptions)
@@ -120,11 +112,7 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
         return Task.FromResult(OpenSessionReply);
     }
 
-    /// <summary>
-    /// Verifies that the CloseSessionAsync call is recorded and returns the configured reply.
-    /// </summary>
-    /// <param name="request">The CloseSessionRequest to process.</param>
-    /// <param name="callOptions">Call options specifying RPC behavior.</param>
+    /// <inheritdoc />
     public Task<CloseSessionReply> CloseSessionAsync(
         CloseSessionRequest request,
         CallOptions callOptions)
@@ -138,11 +126,7 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
         return Task.FromResult(CloseSessionReply);
     }
 
-    /// <summary>
-    /// Verifies that the InvokeAsync call is recorded and returns the next enqueued reply.
-    /// </summary>
-    /// <param name="request">The MxCommandRequest to process.</param>
-    /// <param name="callOptions">Call options specifying RPC behavior.</param>
+    /// <inheritdoc />
     public Task<MxCommandReply> InvokeAsync(
         MxCommandRequest request,
         CallOptions callOptions)
@@ -156,11 +140,7 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
         return Task.FromResult(_invokeReplies.Dequeue());
     }
 
-    /// <summary>
-    /// Verifies that the StreamEventsAsync call is recorded and yields all enqueued events.
-    /// </summary>
-    /// <param name="request">The StreamEventsRequest to process.</param>
-    /// <param name="callOptions">Call options specifying RPC behavior.</param>
+    /// <inheritdoc />
     public async IAsyncEnumerable<MxEvent> StreamEventsAsync(
         StreamEventsRequest request,
         CallOptions callOptions)
@@ -193,11 +173,7 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
         _events.Add(gatewayEvent);
     }
 
-    /// <summary>
-    /// Records the acknowledge call and returns the next enqueued reply (or default).
-    /// </summary>
-    /// <param name="request">The acknowledge alarm request.</param>
-    /// <param name="callOptions">Call options specifying RPC behavior.</param>
+    /// <inheritdoc />
     public Task<AcknowledgeAlarmReply> AcknowledgeAlarmAsync(
         AcknowledgeAlarmRequest request,
         CallOptions callOptions)
@@ -218,11 +194,7 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
             });
     }
 
-    /// <summary>
-    /// Records the query call and yields each enqueued snapshot.
-    /// </summary>
-    /// <param name="request">The query active alarms request.</param>
-    /// <param name="callOptions">Call options specifying RPC behavior.</param>
+    /// <inheritdoc />
     public async IAsyncEnumerable<ActiveAlarmSnapshot> QueryActiveAlarmsAsync(
         QueryActiveAlarmsRequest request,
         CallOptions callOptions)
@@ -251,11 +223,7 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
         _activeAlarmSnapshots.Add(snapshot);
     }
 
-    /// <summary>
-    /// Records the stream-alarms call and yields each enqueued feed message.
-    /// </summary>
-    /// <param name="request">The stream alarms request.</param>
-    /// <param name="callOptions">Call options specifying RPC behavior.</param>
+    /// <inheritdoc />
     public async IAsyncEnumerable<AlarmFeedMessage> StreamAlarmsAsync(
         StreamAlarmsRequest request,
         CallOptions callOptions)

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/GalaxyRepositoryClientTests.cs

@@ -9,6 +9,7 @@ public sealed class GalaxyRepositoryClientTests
     /// <summary>
     /// Verifies that TestConnectionAsync attaches the API key in request metadata and returns the Ok flag.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task TestConnectionAsync_AttachesApiKeyMetadataAndReturnsOkFlag()
     {
@@ -27,6 +28,7 @@ public sealed class GalaxyRepositoryClientTests
     /// <summary>
     /// Verifies that TestConnectionAsync returns false when the server reports NotOk.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task TestConnectionAsync_ReturnsFalseWhenServerReportsNotOk()
     {
@@ -42,6 +44,7 @@ public sealed class GalaxyRepositoryClientTests
     /// <summary>
     /// Verifies that GetLastDeployTimeAsync returns null when the server reports not present.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task GetLastDeployTimeAsync_ReturnsNullWhenNotPresent()
     {
@@ -58,6 +61,7 @@ public sealed class GalaxyRepositoryClientTests
     /// <summary>
     /// Verifies that GetLastDeployTimeAsync returns the timestamp when the server reports it present.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task GetLastDeployTimeAsync_ReturnsTimestampWhenPresent()
     {
@@ -79,6 +83,7 @@ public sealed class GalaxyRepositoryClientTests
     /// <summary>
     /// Verifies that DiscoverHierarchyAsync returns the objects from the server reply.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task DiscoverHierarchyAsync_ReturnsObjectsFromReply()
     {
@@ -141,6 +146,7 @@ public sealed class GalaxyRepositoryClientTests
     /// <summary>
     /// Verifies that DiscoverHierarchyAsync propagates cancellation tokens to the transport.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task DiscoverHierarchyAsync_PropagatesCancellationToTransport()
     {
@@ -161,6 +167,7 @@ public sealed class GalaxyRepositoryClientTests
     /// <summary>
     /// Verifies that TestConnectionAsync retries on transient gRPC failures.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task DiscoverHierarchyAsync_WithRepeatedPageToken_ThrowsProtocolError()
     {
@@ -184,6 +191,7 @@ public sealed class GalaxyRepositoryClientTests
     /// <summary>
     /// Verifies that DiscoverHierarchyAsync maps typed filter options correctly to the request.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task DiscoverHierarchyAsync_WithOptions_MapsTypedFilters()
     {
@@ -218,6 +226,7 @@ public sealed class GalaxyRepositoryClientTests
     /// <summary>
     /// Verifies that TestConnectionAsync retries on transient gRPC failures.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task TestConnectionAsync_RetriesOnTransientGrpcFailure()
     {
@@ -235,6 +244,7 @@ public sealed class GalaxyRepositoryClientTests
     /// <summary>
     /// Verifies that DiscoverHierarchyAsync retries on transient gRPC failures.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task DiscoverHierarchyAsync_RetriesOnTransientGrpcFailure()
     {
@@ -251,6 +261,7 @@ public sealed class GalaxyRepositoryClientTests
     /// <summary>
     /// Verifies that WatchDeployEventsAsync delivers the bootstrap event.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task WatchDeployEventsAsync_DeliversBootstrapEvent()
     {
@@ -287,6 +298,7 @@ public sealed class GalaxyRepositoryClientTests
     /// <summary>
     /// Verifies that WatchDeployEventsAsync delivers multiple events in order.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task WatchDeployEventsAsync_DeliversMultipleEventsInOrder()
     {
@@ -325,6 +337,7 @@ public sealed class GalaxyRepositoryClientTests
     /// <summary>
     /// Verifies that WatchDeployEventsAsync stops iteration cleanly when cancelled.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task WatchDeployEventsAsync_CancellationStopsIterationCleanly()
     {
@@ -369,6 +382,7 @@ public sealed class GalaxyRepositoryClientTests
     /// <summary>
     /// Verifies that WatchDeployEventsAsync throws ObjectDisposedException after the client is disposed.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task WatchDeployEventsAsync_ThrowsAfterDisposal()
     {
@@ -384,6 +398,7 @@ public sealed class GalaxyRepositoryClientTests
     /// <summary>
     /// Verifies that TestConnectionAsync throws ObjectDisposedException after the client is disposed.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task TestConnectionAsync_ThrowsAfterDisposal()
     {

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/LazyBrowseNodeTests.cs

@@ -12,6 +12,7 @@ public sealed class LazyBrowseNodeTests
     /// Verifies that calling BrowseAsync with no parent returns the root nodes
     /// from the first BrowseChildren reply and surfaces the per-child has-children hint.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Browse_NoParent_ReturnsRoots()
     {
@@ -36,6 +37,7 @@ public sealed class LazyBrowseNodeTests
     /// <summary>
     /// Verifies that ExpandAsync populates Children and marks the node expanded after one RPC.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Expand_PopulatesChildrenAndMarksExpanded()
     {
@@ -62,6 +64,7 @@ public sealed class LazyBrowseNodeTests
     /// <summary>
     /// Verifies that a second ExpandAsync call is a no-op and issues no additional RPC.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Expand_CalledTwice_NoSecondRpc()
     {
@@ -86,6 +89,7 @@ public sealed class LazyBrowseNodeTests
     /// <summary>
     /// Verifies that an RPC failure (NotFound) during expand is wrapped in MxGatewayException.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Expand_UnknownParent_ThrowsMxGatewayException()
     {
@@ -113,6 +117,7 @@ public sealed class LazyBrowseNodeTests
     /// <summary>
     /// Verifies that ExpandAsync drains multi-page sibling replies and forwards the page token.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Expand_MultiPageSiblings_GathersAllPages()
     {
@@ -147,6 +152,7 @@ public sealed class LazyBrowseNodeTests
     /// <summary>
     /// Verifies that ten concurrent ExpandAsync calls issue exactly one RPC, not ten.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Expand_CalledConcurrently_OnlyFiresOneRpc()
     {
@@ -178,6 +184,7 @@ public sealed class LazyBrowseNodeTests
     /// <summary>
     /// Verifies that BrowseChildrenOptions filter fields are forwarded to the BrowseChildren request.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Browse_WithFilter_ForwardsToRequest()
     {

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/MxGatewayClientAlarmsTests.cs

@@ -12,6 +12,7 @@ namespace ZB.MOM.WW.MxGateway.Client.Tests;
 public sealed class MxGatewayClientAlarmsTests
 {
     /// <summary>AcknowledgeAlarmAsync records request and returns reply.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task AcknowledgeAlarmAsync_RecordsRequestShapeAndReturnsReply()
     {
@@ -48,6 +49,7 @@ public sealed class MxGatewayClientAlarmsTests
     }
 
     /// <summary>AcknowledgeAlarmAsync honors cancellation.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task AcknowledgeAlarmAsync_HonorsCancellation()
     {
@@ -72,6 +74,7 @@ public sealed class MxGatewayClientAlarmsTests
     }
 
     /// <summary>AcknowledgeAlarmAsync maps unauthenticated RPC exception to typed exception.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task AcknowledgeAlarmAsync_MapsUnauthenticated_RpcException_ToTypedException()
     {
@@ -97,6 +100,7 @@ public sealed class MxGatewayClientAlarmsTests
     }
 
     /// <summary>QueryActiveAlarmsAsync streams enqueued snapshots.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task QueryActiveAlarmsAsync_StreamsEnqueuedSnapshots()
     {
@@ -122,6 +126,7 @@ public sealed class MxGatewayClientAlarmsTests
     }
 
     /// <summary>QueryActiveAlarmsAsync passes filter prefix.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task QueryActiveAlarmsAsync_PassesFilterPrefix()
     {
@@ -142,6 +147,7 @@ public sealed class MxGatewayClientAlarmsTests
     }
 
     /// <summary>QueryActiveAlarmsAsync honors cancellation during enumeration.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task QueryActiveAlarmsAsync_HonorsCancellationDuringEnumeration()
     {

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/MxGatewayClientCliTests.cs

@@ -24,6 +24,7 @@ public sealed class MxGatewayClientCliTests
     }
 
     /// <summary>Verifies that the version command with --json flag prints JSON protocol versions.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task RunAsync_VersionJson_PrintsJsonProtocolVersions()
     {
@@ -38,6 +39,7 @@ public sealed class MxGatewayClientCliTests
     }
 
     /// <summary>Verifies that the write command builds a write request and prints JSON reply.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task RunAsync_Write_BuildsWriteCommandAndPrintsJsonReply()
     {
@@ -83,6 +85,7 @@ public sealed class MxGatewayClientCliTests
     }
 
     /// <summary>Verifies that error output redacts sensitive API key values.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task RunAsync_ErrorOutput_RedactsApiKey()
     {
@@ -107,6 +110,7 @@ public sealed class MxGatewayClientCliTests
     }
 
     /// <summary>Verifies that stream-events with max-events limit stops output in non-JSON format.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task RunAsync_StreamEvents_WithMaxEventsStopsNonJsonOutput()
     {
@@ -149,6 +153,7 @@ public sealed class MxGatewayClientCliTests
 
 
     /// <summary>Verifies that stream-alarms with --max-events stops output and distinguishes payload cases.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task RunAsync_StreamAlarms_WithMaxEventsStopsAndDistinguishesPayloadCases()
     {
@@ -188,6 +193,7 @@ public sealed class MxGatewayClientCliTests
     }
 
     /// <summary>Verifies that acknowledge-alarm builds a request and prints the JSON reply.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task RunAsync_AcknowledgeAlarm_BuildsRequestAndPrintsJsonReply()
     {
@@ -230,6 +236,7 @@ public sealed class MxGatewayClientCliTests
     }
 
     /// <summary>Verifies that smoke command closes opened session when a command fails.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task RunAsync_Smoke_WhenCommandFails_ClosesOpenedSession()
     {
@@ -261,6 +268,7 @@ public sealed class MxGatewayClientCliTests
     }
 
     /// <summary>Verifies that galaxy-test-connection command prints JSON reply.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task RunAsync_GalaxyTestConnection_PrintsJsonReply()
     {
@@ -291,6 +299,7 @@ public sealed class MxGatewayClientCliTests
     }
 
     /// <summary>Verifies that galaxy-discover command prints hierarchy summary.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task RunAsync_GalaxyDiscover_PrintsHierarchySummary()
     {
@@ -361,6 +370,7 @@ public sealed class MxGatewayClientCliTests
     }
 
     /// <summary>Verifies that galaxy-watch command prints text output for deploy events.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task RunAsync_GalaxyWatch_PrintsTextOutputForEvents()
     {
@@ -415,6 +425,7 @@ public sealed class MxGatewayClientCliTests
     }
 
     /// <summary>Verifies that galaxy-watch with --json emits one JSON object per event.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task RunAsync_GalaxyWatch_JsonEmitsOneObjectPerEvent()
     {
@@ -450,6 +461,7 @@ public sealed class MxGatewayClientCliTests
     }
 
     /// <summary>Verifies that batch mode dispatches a single version command and emits the EOR sentinel.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task RunAsync_Batch_DispatchesVersionAndWritesEndOfRecord()
     {
@@ -476,6 +488,7 @@ public sealed class MxGatewayClientCliTests
     }
 
     /// <summary>Verifies that batch mode routes per-command errors to stdout as JSON between EOR markers.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task RunAsync_Batch_WritesErrorsToStdoutAsJson()
     {
@@ -520,6 +533,7 @@ public sealed class MxGatewayClientCliTests
     /// against exit code 0.
     /// </summary>
     /// <param name="command">The alarm subcommand to validate (e.g. "stream-alarms", "acknowledge-alarm").</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Theory]
     [InlineData("stream-alarms")]
     [InlineData("acknowledge-alarm")]
@@ -574,6 +588,7 @@ public sealed class MxGatewayClientCliTests
     /// against a zero server handle. The fix must fail loudly with a
     /// descriptive <see cref="MxGatewayException"/>.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task RunAsync_BenchReadBulk_WhenRegisterReplyMissingTypedPayload_FailsLoudly()
     {
@@ -624,6 +639,7 @@ public sealed class MxGatewayClientCliTests
     /// kept spinning until <c>--duration-seconds</c> elapsed. After the fix
     /// the bench must exit promptly when the supplied token cancels.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task RunAsync_BenchReadBulk_WhenSteadyStateLoopReceivesCancellation_ExitsPromptly()
     {
@@ -718,6 +734,7 @@ public sealed class MxGatewayClientCliTests
     /// to ~49.7 days. The fix must reject negatives with a clear error.
     /// </summary>
     /// <param name="command">The bulk-read subcommand to validate (e.g. "read-bulk", "bench-read-bulk").</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Theory]
     [InlineData("read-bulk")]
     [InlineData("bench-read-bulk")]
@@ -880,7 +897,8 @@ public sealed class MxGatewayClientCliTests
         /// <summary>Optional per-call handler that overrides queue-based behaviour.</summary>
         public Func<MxCommandRequest, CancellationToken, Task<MxCommandReply>>? InvokeHandler { get; init; }
 
-        /// <inheritdoc />
+        /// <summary>Releases resources held by the fake CLI client.</summary>
+        /// <returns>A completed value task.</returns>
         public ValueTask DisposeAsync()
         {
             return ValueTask.CompletedTask;

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/MxGatewayClientSessionTests.cs

@@ -7,6 +7,7 @@ namespace ZB.MOM.WW.MxGateway.Client.Tests;
 public sealed class MxGatewayClientSessionTests
 {
     /// <summary>Verifies that open session attaches API key metadata and cancellation token.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task OpenSessionRawAsync_AttachesApiKeyMetadataAndCancellation()
     {
@@ -22,6 +23,7 @@ public sealed class MxGatewayClientSessionTests
     }
 
     /// <summary>Verifies that open session returns a session with the raw open reply.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task OpenSessionAsync_ReturnsSessionWithRawOpenReply()
     {
@@ -37,6 +39,7 @@ public sealed class MxGatewayClientSessionTests
     }
 
     /// <summary>Verifies that register builds a register command and returns server handle.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task RegisterAsync_BuildsRegisterCommandAndReturnsServerHandle()
     {
@@ -62,6 +65,7 @@ public sealed class MxGatewayClientSessionTests
     }
 
     /// <summary>Verifies that add item 2 builds a command with the specified context.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task AddItem2Async_BuildsAddItem2CommandWithContext()
     {
@@ -87,6 +91,7 @@ public sealed class MxGatewayClientSessionTests
     }
 
     /// <summary>Verifies that write raw builds a write command with the raw value.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task WriteRawAsync_BuildsWriteCommandWithRawValue()
     {
@@ -118,6 +123,7 @@ public sealed class MxGatewayClientSessionTests
     }
 
     /// <summary>Verifies that write 2 raw builds a write 2 command with value and timestamp.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Write2RawAsync_BuildsWrite2CommandWithValueAndTimestamp()
     {
@@ -146,6 +152,7 @@ public sealed class MxGatewayClientSessionTests
     }
 
     /// <summary>Verifies that subscribe bulk builds one command and returns per-item results.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task SubscribeBulkAsync_BuildsOneBulkCommandAndReturnsPerItemResults()
     {
@@ -185,6 +192,7 @@ public sealed class MxGatewayClientSessionTests
     }
 
     /// <summary>Verifies that stream events yields events in the order received from the gateway.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task StreamEventsAsync_YieldsEventsInGatewayOrder()
     {
@@ -216,6 +224,7 @@ public sealed class MxGatewayClientSessionTests
     }
 
     /// <summary>Verifies that close is explicit and idempotent.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task CloseAsync_IsExplicitAndIdempotent()
     {
@@ -232,6 +241,7 @@ public sealed class MxGatewayClientSessionTests
     }
 
     /// <summary>Verifies that invoke retries safe diagnostic commands on transient RPC failure.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task InvokeAsync_RetriesSafeDiagnosticCommandOnTransientGrpcFailure()
     {
@@ -256,6 +266,7 @@ public sealed class MxGatewayClientSessionTests
     }
 
     /// <summary>Verifies that open session does not retry on transient RPC failure.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task OpenSessionAsync_DoesNotRetryTransientGrpcFailure()
     {
@@ -269,6 +280,7 @@ public sealed class MxGatewayClientSessionTests
     }
 
     /// <summary>Verifies that invoke does not retry write commands on transient RPC failure.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task InvokeAsync_DoesNotRetryWriteCommand()
     {
@@ -284,6 +296,7 @@ public sealed class MxGatewayClientSessionTests
     }
 
     /// <summary>Verifies that invoke helpers pass cancellation token to the transport.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task InvokeHelpers_PassCancellationTokenToTransport()
     {

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/MxGatewayGeneratedContractTests.cs

@@ -3,6 +3,7 @@ namespace ZB.MOM.WW.MxGateway.Client.Tests;
 public sealed class MxGatewayGeneratedContractTests
 {
     /// <summary>Verifies that the generated gRPC client can be instantiated from the client factory.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task GeneratedGrpcClient_CanBeConstructedFromClientFactory()
     {

clients/dotnet/ZB.MOM.WW.MxGateway.Client/GalaxyRepositoryClient.cs

@@ -337,6 +337,9 @@ public sealed class GalaxyRepositoryClient : IAsyncDisposable
             cancellationToken);
     }
 
+    /// <summary>Builds a <see cref="BrowseChildrenRequest"/> from the provided options.</summary>
+    /// <param name="options">Browse children options to convert.</param>
+    /// <returns>The constructed request message.</returns>
     internal static BrowseChildrenRequest BuildBrowseChildrenRequest(BrowseChildrenOptions options)
     {
         ArgumentNullException.ThrowIfNull(options);
@@ -424,6 +427,7 @@ public sealed class GalaxyRepositoryClient : IAsyncDisposable
     /// <summary>
     /// Closes the gRPC channel and releases resources.
     /// </summary>
+    /// <returns>A task that represents the asynchronous dispose operation.</returns>
     public ValueTask DisposeAsync()
     {
         if (_disposed)
@@ -493,6 +497,9 @@ public sealed class GalaxyRepositoryClient : IAsyncDisposable
     private static HttpMessageHandler CreateHttpHandler(MxGatewayClientOptions options) =>
         CreateHttpHandlerForTests(options);
 
+    /// <summary>Creates an <see cref="HttpMessageHandler"/> configured from the provided options for test use.</summary>
+    /// <param name="options">Client options used to configure TLS and timeouts.</param>
+    /// <returns>The configured HTTP message handler.</returns>
     internal static SocketsHttpHandler CreateHttpHandlerForTests(MxGatewayClientOptions options)
     {
         SocketsHttpHandler handler = new()

clients/dotnet/ZB.MOM.WW.MxGateway.Client/GrpcGalaxyRepositoryClientTransport.cs

@@ -10,9 +10,7 @@ internal sealed class GrpcGalaxyRepositoryClientTransport(
     MxGatewayClientOptions options,
     GalaxyRepository.GalaxyRepositoryClient rawClient) : IGalaxyRepositoryClientTransport
 {
-    /// <summary>
-    /// Gets the gateway client options.
-    /// </summary>
+    /// <inheritdoc />
     public MxGatewayClientOptions Options { get; } = options;
 
     /// <summary>
@@ -91,7 +89,11 @@ internal sealed class GrpcGalaxyRepositoryClientTransport(
         }
     }
 
-    /// <inheritdoc />
+    /// <summary>Streams deploy events from the Galaxy Repository, using an explicit cancellation token that overrides the call options token when provided.</summary>
+    /// <param name="request">The watch deploy events request.</param>
+    /// <param name="callOptions">Call options for the underlying gRPC call.</param>
+    /// <param name="cancellationToken">Optional cancellation token; takes precedence over the token in <paramref name="callOptions"/> when cancellable.</param>
+    /// <returns>An async enumerable of deploy events.</returns>
     public async IAsyncEnumerable<DeployEvent> WatchDeployEventsAsync(
         WatchDeployEventsRequest request,
         CallOptions callOptions,

clients/dotnet/ZB.MOM.WW.MxGateway.Client/GrpcMxGatewayClientTransport.cs

@@ -10,9 +10,7 @@ internal sealed class GrpcMxGatewayClientTransport(
     MxGatewayClientOptions options,
     MxAccessGateway.MxAccessGatewayClient rawClient) : IMxGatewayClientTransport
 {
-    /// <summary>
-    /// Gets the gateway client options.
-    /// </summary>
+    /// <inheritdoc />
     public MxGatewayClientOptions Options { get; } = options;
 
     /// <summary>
@@ -74,7 +72,11 @@ internal sealed class GrpcMxGatewayClientTransport(
         }
     }
 
-    /// <inheritdoc />
+    /// <summary>Streams MXAccess events from the gateway, forwarding an explicit cancellation token to the stream reader.</summary>
+    /// <param name="request">The stream events request.</param>
+    /// <param name="callOptions">gRPC call options.</param>
+    /// <param name="cancellationToken">Token to cancel the streaming enumeration.</param>
+    /// <returns>An async enumerable of MXAccess events.</returns>
     public async IAsyncEnumerable<MxEvent> StreamEventsAsync(
         StreamEventsRequest request,
         CallOptions callOptions,
@@ -133,7 +135,11 @@ internal sealed class GrpcMxGatewayClientTransport(
         }
     }
 
-    /// <inheritdoc />
+    /// <summary>Queries active alarms from the gateway, forwarding an explicit cancellation token to the stream reader.</summary>
+    /// <param name="request">The query active alarms request.</param>
+    /// <param name="callOptions">gRPC call options.</param>
+    /// <param name="cancellationToken">Token to cancel the streaming enumeration.</param>
+    /// <returns>An async enumerable of active alarm snapshots.</returns>
     public async IAsyncEnumerable<ActiveAlarmSnapshot> QueryActiveAlarmsAsync(
         QueryActiveAlarmsRequest request,
         CallOptions callOptions,
@@ -175,7 +181,11 @@ internal sealed class GrpcMxGatewayClientTransport(
         return QueryActiveAlarmsAsync(request, callOptions);
     }
 
-    /// <inheritdoc />
+    /// <summary>Streams alarm feed messages from the gateway, forwarding an explicit cancellation token to the stream reader.</summary>
+    /// <param name="request">The stream alarms request.</param>
+    /// <param name="callOptions">gRPC call options.</param>
+    /// <param name="cancellationToken">Token to cancel the streaming enumeration.</param>
+    /// <returns>An async enumerable of alarm feed messages.</returns>
     public async IAsyncEnumerable<AlarmFeedMessage> StreamAlarmsAsync(
         StreamAlarmsRequest request,
         CallOptions callOptions,

clients/dotnet/ZB.MOM.WW.MxGateway.Client/IGalaxyRepositoryClientTransport.cs

@@ -15,6 +15,7 @@ internal interface IGalaxyRepositoryClientTransport
     /// <summary>Tests the connection to the Galaxy Repository server.</summary>
     /// <param name="request">The test connection request.</param>
     /// <param name="callOptions">gRPC call options (timeout, cancellation, etc.).</param>
+    /// <returns>A task that resolves to the test connection reply.</returns>
     Task<TestConnectionReply> TestConnectionAsync(
         TestConnectionRequest request,
         CallOptions callOptions);
@@ -22,6 +23,7 @@ internal interface IGalaxyRepositoryClientTransport
     /// <summary>Gets the last deploy time from the Galaxy Repository server.</summary>
     /// <param name="request">The get last deploy time request.</param>
     /// <param name="callOptions">gRPC call options (timeout, cancellation, etc.).</param>
+    /// <returns>A task that resolves to the last deploy time reply.</returns>
     Task<GetLastDeployTimeReply> GetLastDeployTimeAsync(
         GetLastDeployTimeRequest request,
         CallOptions callOptions);
@@ -29,6 +31,7 @@ internal interface IGalaxyRepositoryClientTransport
     /// <summary>Discovers the object hierarchy in the Galaxy Repository.</summary>
     /// <param name="request">The discover hierarchy request.</param>
     /// <param name="callOptions">gRPC call options (timeout, cancellation, etc.).</param>
+    /// <returns>A task that resolves to the hierarchy discovery reply.</returns>
     Task<DiscoverHierarchyReply> DiscoverHierarchyAsync(
         DiscoverHierarchyRequest request,
         CallOptions callOptions);
@@ -36,6 +39,7 @@ internal interface IGalaxyRepositoryClientTransport
     /// <summary>Returns direct children of a parent in the Galaxy hierarchy.</summary>
     /// <param name="request">The browse children request.</param>
     /// <param name="callOptions">gRPC call options (timeout, cancellation, etc.).</param>
+    /// <returns>A task that resolves to the browse children reply.</returns>
     Task<BrowseChildrenReply> BrowseChildrenAsync(
         BrowseChildrenRequest request,
         CallOptions callOptions);
@@ -43,6 +47,7 @@ internal interface IGalaxyRepositoryClientTransport
     /// <summary>Watches for deployment events from the Galaxy Repository server.</summary>
     /// <param name="request">The watch deploy events request.</param>
     /// <param name="callOptions">gRPC call options (timeout, cancellation, etc.).</param>
+    /// <returns>An async enumerable of deploy events.</returns>
     IAsyncEnumerable<DeployEvent> WatchDeployEventsAsync(
         WatchDeployEventsRequest request,
         CallOptions callOptions);

clients/dotnet/ZB.MOM.WW.MxGateway.Client/LazyBrowseNode.cs

@@ -16,6 +16,11 @@ public sealed class LazyBrowseNode
     private readonly SemaphoreSlim _expandLock = new(1, 1);
     private bool _isExpanded;
 
+    /// <summary>Initializes a new instance of <see cref="LazyBrowseNode"/>.</summary>
+    /// <param name="client">The repository client used to fetch children.</param>
+    /// <param name="object">The underlying Galaxy object for this node.</param>
+    /// <param name="hasChildrenHint">True when the server reports the node has at least one matching descendant.</param>
+    /// <param name="options">Options controlling child browse behavior.</param>
     internal LazyBrowseNode(
         GalaxyRepositoryClient client,
         GalaxyObject @object,
@@ -49,6 +54,7 @@ public sealed class LazyBrowseNode
     ///     (after the first completes) return immediately.
     /// </remarks>
     /// <param name="cancellationToken">Token to observe for cancellation.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     public async Task ExpandAsync(CancellationToken cancellationToken = default)
     {
         if (_isExpanded)

clients/dotnet/ZB.MOM.WW.MxGateway.Client/MxCommandReplyExtensions.cs

@@ -7,6 +7,7 @@ public static class MxCommandReplyExtensions
 {
     /// <summary>Validates that the reply has a successful protocol status (Ok or MxAccessFailure), throwing a gateway exception if not.</summary>
     /// <param name="reply">The command reply to check.</param>
+    /// <returns>The same <paramref name="reply"/> for fluent chaining when validation passes.</returns>
     public static MxCommandReply EnsureProtocolSuccess(this MxCommandReply reply)
     {
         ArgumentNullException.ThrowIfNull(reply);
@@ -24,6 +25,7 @@ public static class MxCommandReplyExtensions
 
     /// <summary>Validates that the reply indicates MXAccess success (no HResult or status failures), throwing MxAccessException if not.</summary>
     /// <param name="reply">The command reply to check.</param>
+    /// <returns>The same <paramref name="reply"/> for fluent chaining when validation passes.</returns>
     public static MxCommandReply EnsureMxAccessSuccess(this MxCommandReply reply)
     {
         ArgumentNullException.ThrowIfNull(reply);

clients/dotnet/ZB.MOM.WW.MxGateway.Client/MxGatewayClient.cs

@@ -249,6 +249,7 @@ public sealed class MxGatewayClient : IAsyncDisposable
     /// <summary>
     /// Disposes the client and releases all resources.
     /// </summary>
+    /// <returns>A task that represents the asynchronous dispose operation.</returns>
     public ValueTask DisposeAsync()
     {
         if (_disposed)
@@ -318,6 +319,9 @@ public sealed class MxGatewayClient : IAsyncDisposable
     private static HttpMessageHandler CreateHttpHandler(MxGatewayClientOptions options) =>
         CreateHttpHandlerForTests(options);
 
+    /// <summary>Creates an <see cref="HttpMessageHandler"/> configured from the provided options for test use.</summary>
+    /// <param name="options">Client options used to configure TLS and timeouts.</param>
+    /// <returns>The configured HTTP message handler.</returns>
     internal static SocketsHttpHandler CreateHttpHandlerForTests(MxGatewayClientOptions options)
     {
         SocketsHttpHandler handler = new()

clients/dotnet/ZB.MOM.WW.MxGateway.Client/MxGatewayClientRetryPolicy.cs

@@ -12,6 +12,7 @@ internal static class MxGatewayClientRetryPolicy
     /// <summary>Creates a Polly ResiliencePipeline that retries transient gRPC failures with exponential backoff.</summary>
     /// <param name="options">Retry configuration (max attempts, delay bounds, jitter).</param>
     /// <param name="logger">Optional logger for retry diagnostics.</param>
+    /// <returns>A configured <see cref="ResiliencePipeline"/> with exponential-backoff retry.</returns>
     public static ResiliencePipeline Create(
         MxGatewayClientRetryOptions options,
         ILogger? logger)
@@ -42,6 +43,7 @@ internal static class MxGatewayClientRetryPolicy
 
     /// <summary>Returns whether a command kind is eligible for automatic retry on transient failures.</summary>
     /// <param name="kind">The command kind to check.</param>
+    /// <returns><see langword="true"/> if the command kind is safe to retry; otherwise <see langword="false"/>.</returns>
     public static bool IsRetryableCommand(MxCommandKind kind)
     {
         return kind is MxCommandKind.Ping

clients/dotnet/ZB.MOM.WW.MxGateway.Client/MxGatewaySession.cs

@@ -211,6 +211,7 @@ public sealed class MxGatewaySession : IAsyncDisposable
     /// <param name="serverHandle">The ServerHandle from register.</param>
     /// <param name="itemHandle">The ItemHandle from add-item.</param>
     /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     public async Task AdviseAsync(
         int serverHandle,
         int itemHandle,
@@ -252,6 +253,7 @@ public sealed class MxGatewaySession : IAsyncDisposable
     /// <param name="serverHandle">The ServerHandle from register.</param>
     /// <param name="itemHandle">The ItemHandle from add-item.</param>
     /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     public async Task UnAdviseAsync(
         int serverHandle,
         int itemHandle,
@@ -293,6 +295,7 @@ public sealed class MxGatewaySession : IAsyncDisposable
     /// <param name="serverHandle">The ServerHandle from register.</param>
     /// <param name="itemHandle">The ItemHandle from add-item.</param>
     /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     public async Task RemoveItemAsync(
         int serverHandle,
         int itemHandle,
@@ -675,6 +678,7 @@ public sealed class MxGatewaySession : IAsyncDisposable
     /// <param name="value">The value to write.</param>
     /// <param name="userId">User ID context for the write.</param>
     /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     public async Task WriteAsync(
         int serverHandle,
         int itemHandle,
@@ -729,6 +733,7 @@ public sealed class MxGatewaySession : IAsyncDisposable
     /// <param name="timestampValue">The timestamp to write with the value.</param>
     /// <param name="userId">User ID context for the write.</param>
     /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     public async Task Write2Async(
         int serverHandle,
         int itemHandle,
@@ -821,6 +826,7 @@ public sealed class MxGatewaySession : IAsyncDisposable
     /// <summary>
     /// Closes the session and releases resources.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     public async ValueTask DisposeAsync()
     {
         await CloseAsync().ConfigureAwait(false);

clients/dotnet/ZB.MOM.WW.MxGateway.Client/MxStatusProxyExtensions.cs

@@ -7,6 +7,7 @@ public static class MxStatusProxyExtensions
 {
     /// <summary>Returns whether the status indicates success (success flag set and category is Ok).</summary>
     /// <param name="status">The status to check.</param>
+    /// <returns><c>true</c> if the status is successful; <c>false</c> otherwise.</returns>
     public static bool IsSuccess(this MxStatusProxy status)
     {
         ArgumentNullException.ThrowIfNull(status);
@@ -17,6 +18,7 @@ public static class MxStatusProxyExtensions
 
     /// <summary>Returns a formatted summary of the status for diagnostic output.</summary>
     /// <param name="status">The status to summarize.</param>
+    /// <returns>A human-readable string combining category, source, detail, and diagnostic text.</returns>
     public static string ToDiagnosticSummary(this MxStatusProxy status)
     {
         ArgumentNullException.ThrowIfNull(status);

clients/dotnet/ZB.MOM.WW.MxGateway.Client/MxValueExtensions.cs

@@ -14,6 +14,7 @@ public static class MxValueExtensions
     /// Converts a boolean value to an MxValue with MxDataType.Boolean.
     /// </summary>
     /// <param name="value">Scalar boolean value to wrap.</param>
+    /// <returns>An <see cref="MxValue"/> with <c>MxDataType.Boolean</c>.</returns>
     public static MxValue ToMxValue(this bool value)
     {
         return new MxValue
@@ -28,6 +29,7 @@ public static class MxValueExtensions
     /// Converts a 32-bit integer value to an MxValue with MxDataType.Integer.
     /// </summary>
     /// <param name="value">32-bit integer value to wrap.</param>
+    /// <returns>An <see cref="MxValue"/> with <c>MxDataType.Integer</c>.</returns>
     public static MxValue ToMxValue(this int value)
     {
         return new MxValue
@@ -42,6 +44,7 @@ public static class MxValueExtensions
     /// Converts a 64-bit integer value to an MxValue with MxDataType.Integer.
     /// </summary>
     /// <param name="value">64-bit integer value to wrap.</param>
+    /// <returns>An <see cref="MxValue"/> with <c>MxDataType.Integer</c>.</returns>
     public static MxValue ToMxValue(this long value)
     {
         return new MxValue
@@ -56,6 +59,7 @@ public static class MxValueExtensions
     /// Converts a single-precision floating-point value to an MxValue with MxDataType.Float.
     /// </summary>
     /// <param name="value">Single-precision floating-point value to wrap.</param>
+    /// <returns>An <see cref="MxValue"/> with <c>MxDataType.Float</c>.</returns>
     public static MxValue ToMxValue(this float value)
     {
         return new MxValue
@@ -70,6 +74,7 @@ public static class MxValueExtensions
     /// Converts a double-precision floating-point value to an MxValue with MxDataType.Double.
     /// </summary>
     /// <param name="value">Double-precision floating-point value to wrap.</param>
+    /// <returns>An <see cref="MxValue"/> with <c>MxDataType.Double</c>.</returns>
     public static MxValue ToMxValue(this double value)
     {
         return new MxValue
@@ -84,6 +89,7 @@ public static class MxValueExtensions
     /// Converts a string value to an MxValue with MxDataType.String.
     /// </summary>
     /// <param name="value">String value to wrap.</param>
+    /// <returns>An <see cref="MxValue"/> with <c>MxDataType.String</c>.</returns>
     public static MxValue ToMxValue(this string value)
     {
         ArgumentNullException.ThrowIfNull(value);
@@ -100,6 +106,7 @@ public static class MxValueExtensions
     /// Converts a DateTimeOffset value to an MxValue with MxDataType.Time.
     /// </summary>
     /// <param name="value">DateTimeOffset value to wrap.</param>
+    /// <returns>An <see cref="MxValue"/> with <c>MxDataType.Time</c>.</returns>
     public static MxValue ToMxValue(this DateTimeOffset value)
     {
         return new MxValue
@@ -114,6 +121,7 @@ public static class MxValueExtensions
     /// Converts a DateTime value to an MxValue with MxDataType.Time.
     /// </summary>
     /// <param name="value">DateTime value to wrap.</param>
+    /// <returns>An <see cref="MxValue"/> with <c>MxDataType.Time</c>.</returns>
     public static MxValue ToMxValue(this DateTime value)
     {
         return new DateTimeOffset(
@@ -127,6 +135,7 @@ public static class MxValueExtensions
     /// Converts a boolean array to an MxValue with MxDataType.Boolean.
     /// </summary>
     /// <param name="values">Array of boolean values to wrap.</param>
+    /// <returns>An <see cref="MxValue"/> with <c>MxDataType.Boolean</c> and an array payload.</returns>
     public static MxValue ToMxValue(this IReadOnlyList<bool> values)
     {
         ArgumentNullException.ThrowIfNull(values);
@@ -145,6 +154,7 @@ public static class MxValueExtensions
     /// Converts a 32-bit integer array to an MxValue with MxDataType.Integer.
     /// </summary>
     /// <param name="values">Array of 32-bit integer values to wrap.</param>
+    /// <returns>An <see cref="MxValue"/> with <c>MxDataType.Integer</c> and an array payload.</returns>
     public static MxValue ToMxValue(this IReadOnlyList<int> values)
     {
         ArgumentNullException.ThrowIfNull(values);
@@ -163,6 +173,7 @@ public static class MxValueExtensions
     /// Converts a 64-bit integer array to an MxValue with MxDataType.Integer.
     /// </summary>
     /// <param name="values">Array of 64-bit integer values to wrap.</param>
+    /// <returns>An <see cref="MxValue"/> with <c>MxDataType.Integer</c> and an array payload.</returns>
     public static MxValue ToMxValue(this IReadOnlyList<long> values)
     {
         ArgumentNullException.ThrowIfNull(values);
@@ -181,6 +192,7 @@ public static class MxValueExtensions
     /// Converts a single-precision floating-point array to an MxValue with MxDataType.Float.
     /// </summary>
     /// <param name="values">Array of single-precision floating-point values to wrap.</param>
+    /// <returns>An <see cref="MxValue"/> with <c>MxDataType.Float</c> and an array payload.</returns>
     public static MxValue ToMxValue(this IReadOnlyList<float> values)
     {
         ArgumentNullException.ThrowIfNull(values);
@@ -199,6 +211,7 @@ public static class MxValueExtensions
     /// Converts a double-precision floating-point array to an MxValue with MxDataType.Double.
     /// </summary>
     /// <param name="values">Array of double-precision floating-point values to wrap.</param>
+    /// <returns>An <see cref="MxValue"/> with <c>MxDataType.Double</c> and an array payload.</returns>
     public static MxValue ToMxValue(this IReadOnlyList<double> values)
     {
         ArgumentNullException.ThrowIfNull(values);
@@ -217,6 +230,7 @@ public static class MxValueExtensions
     /// Converts a string array to an MxValue with MxDataType.String.
     /// </summary>
     /// <param name="values">Array of string values to wrap.</param>
+    /// <returns>An <see cref="MxValue"/> with <c>MxDataType.String</c> and an array payload.</returns>
     public static MxValue ToMxValue(this IReadOnlyList<string> values)
     {
         ArgumentNullException.ThrowIfNull(values);
@@ -235,6 +249,7 @@ public static class MxValueExtensions
     /// Converts a DateTimeOffset array to an MxValue with MxDataType.Time.
     /// </summary>
     /// <param name="values">Array of DateTimeOffset values to wrap.</param>
+    /// <returns>An <see cref="MxValue"/> with <c>MxDataType.Time</c> and an array payload.</returns>
     public static MxValue ToMxValue(this IReadOnlyList<DateTimeOffset> values)
     {
         ArgumentNullException.ThrowIfNull(values);
@@ -253,6 +268,7 @@ public static class MxValueExtensions
     /// Gets the projection kind (field name) of the given MxValue's current oneof value.
     /// </summary>
     /// <param name="value">The MxValue whose oneof projection kind is returned.</param>
+    /// <returns>The JSON field name of the active oneof case, or <c>"nullValue"</c>/<c>"unspecified"</c> for null/unset values.</returns>
     public static string GetProjectionKind(this MxValue value)
     {
         ArgumentNullException.ThrowIfNull(value);
@@ -276,6 +292,7 @@ public static class MxValueExtensions
     /// Converts an MxValue to a CLR object; returns the boxed value or null for null MxValues.
     /// </summary>
     /// <param name="value">The MxValue to convert.</param>
+    /// <returns>The boxed CLR value, or null if the MxValue represents a null.</returns>
     public static object? ToClrValue(this MxValue value)
     {
         ArgumentNullException.ThrowIfNull(value);
@@ -299,6 +316,7 @@ public static class MxValueExtensions
     /// Converts an MxArray to a CLR array; returns null if the array does not have a known element type.
     /// </summary>
     /// <param name="array">The MxArray to convert.</param>
+    /// <returns>A CLR array of the appropriate element type, or null for unknown element types.</returns>
     public static object? ToClrArrayValue(this MxArray array)
     {
         ArgumentNullException.ThrowIfNull(array);
@@ -328,6 +346,7 @@ public static class MxValueExtensions
     /// <param name="variantType">Variant type string (e.g., "VT_BSTR").</param>
     /// <param name="rawDiagnostic">Diagnostic string describing the raw value.</param>
     /// <param name="rawDataType">Optional MXAccess data type override.</param>
+    /// <returns>An <see cref="MxValue"/> with <c>MxDataType.Unknown</c> and the raw byte payload.</returns>
     public static MxValue ToRawMxValue(
         byte[] value,
         string variantType,