client/dotnet: backfill XML doc comments to satisfy analyzers

Adds missing <summary>/<param> docs across the .NET client library and its test suite so CommentChecker reports zero issues. TreatWarningsAsErrors requires the analyzer surface clean before publishing the NuGet package.
2026-05-27 14:30:53 -04:00
parent 615b487a77
commit 795eee72e3
7 changed files with 32 additions and 0 deletions
@@ -48,6 +48,7 @@ internal sealed class FakeGalaxyRepositoryTransport(MxGatewayClientOptions optio
    /// </summary>
    public DiscoverHierarchyReply DiscoverHierarchyReply { get; set; } = new();

+    /// <summary>Gets the queue of discover hierarchy replies; dequeued in FIFO order.</summary>
    public Queue<DiscoverHierarchyReply> DiscoverHierarchyReplies { get; } = new();

    /// <summary>
@@ -196,6 +196,8 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
    /// <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>
    public Task<AcknowledgeAlarmReply> AcknowledgeAlarmAsync(
        AcknowledgeAlarmRequest request,
        CallOptions callOptions)
@@ -219,6 +221,8 @@ 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>
    public async IAsyncEnumerable<ActiveAlarmSnapshot> QueryActiveAlarmsAsync(
        QueryActiveAlarmsRequest request,
        CallOptions callOptions)
@@ -234,12 +238,14 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
    }

    /// <summary>Enqueues an acknowledge reply.</summary>
+    /// <param name="reply">The acknowledge reply to enqueue.</param>
    public void AddAcknowledgeReply(AcknowledgeAlarmReply reply)
    {
        _acknowledgeReplies.Enqueue(reply);
    }

    /// <summary>Enqueues a snapshot to be yielded from QueryActiveAlarmsAsync.</summary>
+    /// <param name="snapshot">The snapshot to enqueue.</param>
    public void AddActiveAlarmSnapshot(ActiveAlarmSnapshot snapshot)
    {
        _activeAlarmSnapshots.Add(snapshot);
@@ -248,6 +254,8 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
    /// <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>
    public async IAsyncEnumerable<AlarmFeedMessage> StreamAlarmsAsync(
        StreamAlarmsRequest request,
        CallOptions callOptions)
@@ -263,6 +271,7 @@ internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMx
    }

    /// <summary>Enqueues an alarm feed message to be yielded from StreamAlarmsAsync.</summary>
+    /// <param name="message">The alarm feed message to enqueue.</param>
    public void AddAlarmFeedMessage(AlarmFeedMessage message)
    {
        _alarmFeedMessages.Add(message);
@@ -181,6 +181,9 @@ public sealed class GalaxyRepositoryClientTests
        Assert.Contains("repeated page token", exception.Message, StringComparison.Ordinal);
    }

+    /// <summary>
+    /// Verifies that DiscoverHierarchyAsync maps typed filter options correctly to the request.
+    /// </summary>
    [Fact]
    public async Task DiscoverHierarchyAsync_WithOptions_MapsTypedFilters()
    {
@@ -212,6 +215,9 @@ public sealed class GalaxyRepositoryClientTests
        Assert.True(request.HistorizedOnly);
    }

+    /// <summary>
+    /// Verifies that TestConnectionAsync retries on transient gRPC failures.
+    /// </summary>
    [Fact]
    public async Task TestConnectionAsync_RetriesOnTransientGrpcFailure()
    {
@@ -11,6 +11,7 @@ namespace ZB.MOM.WW.MxGateway.Client.Tests;
 /// </summary>
 public sealed class MxGatewayClientAlarmsTests
 {
+    /// <summary>AcknowledgeAlarmAsync records request and returns reply.</summary>
    [Fact]
    public async Task AcknowledgeAlarmAsync_RecordsRequestShapeAndReturnsReply()
    {
@@ -46,6 +47,7 @@ public sealed class MxGatewayClientAlarmsTests
        Assert.Equal("Bearer test-api-key", call.CallOptions.Headers?.GetValue("authorization"));
    }

+    /// <summary>AcknowledgeAlarmAsync honors cancellation.</summary>
    [Fact]
    public async Task AcknowledgeAlarmAsync_HonorsCancellation()
    {
@@ -69,6 +71,7 @@ public sealed class MxGatewayClientAlarmsTests
                cancellation.Token));
    }

+    /// <summary>AcknowledgeAlarmAsync maps unauthenticated RPC exception to typed exception.</summary>
    [Fact]
    public async Task AcknowledgeAlarmAsync_MapsUnauthenticated_RpcException_ToTypedException()
    {
@@ -93,6 +96,7 @@ public sealed class MxGatewayClientAlarmsTests
        Assert.Equal(StatusCode.Unauthenticated, ex.StatusCode);
    }

+    /// <summary>QueryActiveAlarmsAsync streams enqueued snapshots.</summary>
    [Fact]
    public async Task QueryActiveAlarmsAsync_StreamsEnqueuedSnapshots()
    {
@@ -117,6 +121,7 @@ public sealed class MxGatewayClientAlarmsTests
        Assert.Single(transport.QueryActiveAlarmsCalls);
    }

+    /// <summary>QueryActiveAlarmsAsync passes filter prefix.</summary>
    [Fact]
    public async Task QueryActiveAlarmsAsync_PassesFilterPrefix()
    {
@@ -136,6 +141,7 @@ public sealed class MxGatewayClientAlarmsTests
        Assert.Equal("Tank01.", call.Request.AlarmFilterPrefix);
    }

+    /// <summary>QueryActiveAlarmsAsync honors cancellation during enumeration.</summary>
    [Fact]
    public async Task QueryActiveAlarmsAsync_HonorsCancellationDuringEnumeration()
    {
@@ -519,6 +519,7 @@ public sealed class MxGatewayClientCliTests
    /// production <see cref="MxGatewayClientCli.RunAsync"/>, and asserted
    /// against exit code 0.
    /// </summary>
+    /// <param name="command">The alarm subcommand to validate (e.g. "stream-alarms", "acknowledge-alarm").</param>
    [Theory]
    [InlineData("stream-alarms")]
    [InlineData("acknowledge-alarm")]
@@ -716,6 +717,7 @@ public sealed class MxGatewayClientCliTests
    /// bounds checking, so a negative value (e.g. <c>-1</c>) silently wraps
    /// 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>
    [Theory]
    [InlineData("read-bulk")]
    [InlineData("bench-read-bulk")]
@@ -988,6 +990,7 @@ public sealed class MxGatewayClientCliTests
        /// <summary>Galaxy discover hierarchy reply to return.</summary>
        public DiscoverHierarchyReply GalaxyDiscoverHierarchyReply { get; set; } = new();

+        /// <summary>Queue of galaxy discover hierarchy replies to return.</summary>
        public Queue<DiscoverHierarchyReply> GalaxyDiscoverHierarchyReplies { get; } = new();

        /// <summary>List of received galaxy test connection requests.</summary>
@@ -182,6 +182,10 @@ public sealed class GalaxyRepositoryClient : IAsyncDisposable
        return await DiscoverHierarchyAsync(new DiscoverHierarchyOptions(), cancellationToken).ConfigureAwait(false);
    }

+    /// <summary>Discovers the Galaxy object hierarchy.</summary>
+    /// <param name="options">Client configuration options.</param>
+    /// <param name="cancellationToken">Token to observe for cancellation.</param>
+    /// <returns>The collection of Galaxy objects in the hierarchy.</returns>
    public async Task<IReadOnlyList<GalaxyObject>> DiscoverHierarchyAsync(
        DiscoverHierarchyOptions options,
        CancellationToken cancellationToken = default)
@@ -47,6 +47,9 @@ public sealed class MxGatewayClientOptions
    /// </summary>
    public TimeSpan? StreamTimeout { get; init; }

+    /// <summary>
+    /// Gets the maximum size in bytes for gRPC messages.
+    /// </summary>
    public int MaxGrpcMessageBytes { get; init; } = 16 * 1024 * 1024;

    /// <summary>