docs: complete XML doc coverage (returns, summaries, inheritdoc)

Resolve all 622 issues flagged by the enhanced CommentChecker: add missing <returns> tags (incl. the standard phrasing on non-generic Task methods), add missing <summary> tags, and replace misused/redundant <inheritdoc/> on members that override or implement nothing with real documentation. Documentation-only — no behavior change; solution builds clean.
2026-06-03 11:39:32 -04:00
parent a050170414
commit eabf270d71
208 changed files with 867 additions and 114 deletions
@@ -31,35 +31,42 @@ public interface IMxGatewayClient : IAsyncDisposable
    /// <summary>Opens the gateway session and registers the client (Register → serverHandle held internally).</summary>
    /// <param name="options">Resolved connection parameters.</param>
    /// <param name="ct">Cancellation token.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    Task ConnectAsync(MxGatewayConnectionOptions options, CancellationToken ct = default);

    /// <summary>Closes the session.</summary>
    /// <param name="ct">Cancellation token.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    Task DisconnectAsync(CancellationToken ct = default);

    /// <summary>AddItem + Advise; returns the gateway item handle (as a string subscription id).</summary>
    /// <param name="tagPath">Tag address to subscribe to.</param>
    /// <param name="ct">Cancellation token.</param>
+    /// <returns>A task that resolves to the gateway item handle (subscription id).</returns>
    Task<string> SubscribeAsync(string tagPath, CancellationToken ct = default);

    /// <summary>UnAdvise + RemoveItem for a previously returned subscription id.</summary>
    /// <param name="subscriptionId">Subscription id returned by <see cref="SubscribeAsync"/>.</param>
    /// <param name="ct">Cancellation token.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    Task UnsubscribeAsync(string subscriptionId, CancellationToken ct = default);

    /// <summary>Snapshot read of one or more tags (ReadBulk).</summary>
    /// <param name="tagPaths">Tag addresses to read.</param>
    /// <param name="ct">Cancellation token.</param>
+    /// <returns>A task that resolves to one outcome per requested tag path.</returns>
    Task<IReadOnlyList<MxReadOutcome>> ReadAsync(IReadOnlyList<string> tagPaths, CancellationToken ct = default);

    /// <summary>Write one or more tag/value pairs (WriteBulk with the configured WriteUserId).</summary>
    /// <param name="writes">Tag/value pairs to write.</param>
    /// <param name="ct">Cancellation token.</param>
+    /// <returns>A task that resolves to one outcome per requested write.</returns>
    Task<IReadOnlyList<MxWriteOutcome>> WriteAsync(IReadOnlyList<(string TagPath, object? Value)> writes, CancellationToken ct = default);

    /// <summary>One Galaxy browse level (BrowseChildren). <paramref name="parentNodeId"/> null → root.</summary>
    /// <param name="parentNodeId">Parent node id (Galaxy contained path), or null for root.</param>
    /// <param name="ct">Cancellation token.</param>
+    /// <returns>A task that resolves to the child nodes and a flag indicating whether the result was truncated.</returns>
    Task<(IReadOnlyList<MxBrowseChild> Children, bool Truncated)> BrowseChildrenAsync(string? parentNodeId, CancellationToken ct = default);

    /// <summary>
@@ -69,6 +76,7 @@ public interface IMxGatewayClient : IAsyncDisposable
    /// </summary>
    /// <param name="onUpdate">Callback invoked per advised-tag value change.</param>
    /// <param name="ct">Cancellation token; ends the loop when cancelled.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    Task RunEventLoopAsync(Action<MxValueUpdate> onUpdate, CancellationToken ct = default);

    /// <summary>
@@ -80,6 +88,7 @@ public interface IMxGatewayClient : IAsyncDisposable
    /// <param name="alarmFilterPrefix">Optional source-reference prefix to scope the feed; null = gateway-wide.</param>
    /// <param name="onTransition">Callback invoked per native alarm transition.</param>
    /// <param name="ct">Cancellation token; ends the loop when cancelled.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    Task RunAlarmStreamAsync(string? alarmFilterPrefix, Action<NativeAlarmTransition> onTransition, CancellationToken ct = default);
 }

@@ -87,5 +96,6 @@ public interface IMxGatewayClient : IAsyncDisposable
 public interface IMxGatewayClientFactory
 {
    /// <summary>Creates a new, unconnected client instance.</summary>
+    /// <returns>A new <see cref="IMxGatewayClient"/> ready to be connected.</returns>
    IMxGatewayClient Create();
 }
@@ -89,6 +89,11 @@ public interface IOpcUaClient : IAsyncDisposable
    /// active conditions as Snapshot…SnapshotComplete transitions. Returns a
    /// handle for <see cref="RemoveAlarmSubscriptionAsync"/>.
    /// </summary>
+    /// <param name="sourceNodeId">OPC UA node ID to monitor; null subscribes to the Server object.</param>
+    /// <param name="conditionFilter">Optional OPC UA condition type filter; null subscribes to all conditions.</param>
+    /// <param name="onTransition">Callback invoked for each alarm transition received from the server.</param>
+    /// <param name="cancellationToken">Token to observe for cancellation.</param>
+    /// <returns>A task that resolves to a subscription handle string for use with <see cref="RemoveAlarmSubscriptionAsync"/>.</returns>
    Task<string> CreateAlarmSubscriptionAsync(
        string? sourceNodeId,
        string? conditionFilter,
@@ -96,6 +101,9 @@ public interface IOpcUaClient : IAsyncDisposable
        CancellationToken cancellationToken = default);

    /// <summary>Removes an alarm-event subscription by handle.</summary>
+    /// <param name="subscriptionHandle">The handle returned by <see cref="CreateAlarmSubscriptionAsync"/>.</param>
+    /// <param name="cancellationToken">Token to observe for cancellation.</param>
+    /// <returns>A task representing the asynchronous operation.</returns>
    Task RemoveAlarmSubscriptionAsync(string subscriptionHandle, CancellationToken cancellationToken = default);

    /// <summary>
@@ -167,7 +175,7 @@ internal class StubOpcUaClient : IOpcUaClient
    /// <inheritdoc />
    public bool IsConnected { get; private set; }
 #pragma warning disable CS0067
-    /// <inheritdoc />
+    /// <summary>Raised when the OPC UA session detects a keep-alive failure or the server becomes unreachable.</summary>
    public event Action? ConnectionLost;
 #pragma warning restore CS0067

@@ -230,7 +238,8 @@ internal class StubOpcUaClient : IOpcUaClient
        string? parentNodeId, CancellationToken cancellationToken = default)
        => throw new NotImplementedException();

-    /// <inheritdoc />
+    /// <summary>Disposes this stub client and marks the connection as closed.</summary>
+    /// <returns>A completed <see cref="ValueTask"/>.</returns>
    public ValueTask DisposeAsync()
    {
        IsConnected = false;
@@ -19,9 +19,14 @@ namespace ZB.MOM.WW.ScadaBridge.DataConnectionLayer.Adapters;
 public static class MxGatewayAlarmMapper
 {
    /// <summary>Clamps the gateway severity onto the unified 0–1000 scale.</summary>
+    /// <param name="severity">Raw gateway severity value to clamp.</param>
+    /// <returns>The severity clamped to the range [0, 1000].</returns>
    public static int NormalizeSeverity(int severity) => Math.Clamp(severity, 0, 1000);

    /// <summary>Maps a gateway condition-state + severity to the unified condition.</summary>
+    /// <param name="state">Gateway proto condition state to map.</param>
+    /// <param name="severity">Raw gateway severity value; normalized to 0–1000.</param>
+    /// <returns>The protocol-neutral <see cref="AlarmConditionState"/> equivalent.</returns>
    public static AlarmConditionState MapConditionState(ProtoConditionState state, int severity)
    {
        var (active, acked) = state switch
@@ -36,6 +41,8 @@ public static class MxGatewayAlarmMapper
    }

    /// <summary>Maps a gateway transition kind to the unified transition kind.</summary>
+    /// <param name="kind">Gateway proto transition kind to map.</param>
+    /// <returns>The protocol-neutral <see cref="AlarmTransitionKind"/> equivalent.</returns>
    public static AlarmTransitionKind MapKind(ProtoTransitionKind kind) => kind switch
    {
        ProtoTransitionKind.Raise => AlarmTransitionKind.Raise,
@@ -61,6 +68,8 @@ public static class MxGatewayAlarmMapper
    }

    /// <summary>Maps a live <see cref="OnAlarmTransitionEvent"/> to a transition.</summary>
+    /// <param name="body">The gateway alarm transition event proto message to map.</param>
+    /// <returns>The protocol-neutral <see cref="NativeAlarmTransition"/>.</returns>
    public static NativeAlarmTransition MapTransition(OnAlarmTransitionEvent body) => new(
        SourceReference: body.AlarmFullReference,
        SourceObjectReference: body.SourceObjectReference,
@@ -78,12 +87,15 @@ public static class MxGatewayAlarmMapper
        LimitValue: "");

    /// <summary>The end-of-snapshot sentinel transition (no condition payload).</summary>
+    /// <returns>A <see cref="NativeAlarmTransition"/> with <c>AlarmTransitionKind.SnapshotComplete</c>.</returns>
    public static NativeAlarmTransition SnapshotComplete() => new(
        "", "", "", AlarmTransitionKind.SnapshotComplete,
        new AlarmConditionState(false, true, null, AlarmShelveState.Unshelved, false, 0),
        "", "", "", "", "", null, DateTimeOffset.UtcNow, "", "");

    /// <summary>Maps one initial-snapshot <see cref="ActiveAlarmSnapshot"/> entry to a Snapshot transition.</summary>
+    /// <param name="snapshot">The active alarm snapshot proto message to map.</param>
+    /// <returns>A <see cref="NativeAlarmTransition"/> with <c>AlarmTransitionKind.Snapshot</c>.</returns>
    public static NativeAlarmTransition MapSnapshot(ActiveAlarmSnapshot snapshot) => new(
        SourceReference: snapshot.AlarmFullReference,
        SourceObjectReference: snapshot.SourceObjectReference,
@@ -262,7 +262,8 @@ public class MxGatewayDataConnection : IDataConnection, IBrowsableDataConnection
        return new BrowseChildrenResult(nodes, truncated);
    }

-    /// <inheritdoc />
+    /// <summary>Cancels the event loop and disposes the underlying MxGateway client.</summary>
+    /// <returns>A <see cref="ValueTask"/> that completes when disposal is finished.</returns>
    public async ValueTask DisposeAsync()
    {
        _eventLoopCts?.Cancel();
@@ -13,9 +13,18 @@ namespace ZB.MOM.WW.ScadaBridge.DataConnectionLayer.Adapters;
 public static class OpcUaAlarmMapper
 {
    /// <summary>Clamps an OPC UA severity (1–1000, sometimes out of range) to the unified 0–1000 scale.</summary>
+    /// <param name="severity">The raw OPC UA severity value to clamp.</param>
+    /// <returns>The severity clamped to the range [0, 1000].</returns>
    public static int NormalizeSeverity(int severity) => Math.Clamp(severity, 0, 1000);

    /// <summary>Builds an <see cref="AlarmConditionState"/> from the orthogonal A&amp;C sub-states.</summary>
+    /// <param name="active">Whether the alarm condition is currently active.</param>
+    /// <param name="acked">Whether the alarm has been acknowledged.</param>
+    /// <param name="confirmed">Whether the alarm has been confirmed; null if not supported by the server.</param>
+    /// <param name="shelve">The current shelving state of the alarm.</param>
+    /// <param name="suppressed">Whether the alarm is suppressed.</param>
+    /// <param name="severity">The raw OPC UA severity (1–1000); clamped via <see cref="NormalizeSeverity"/>.</param>
+    /// <returns>The composed <see cref="AlarmConditionState"/>.</returns>
    public static AlarmConditionState BuildCondition(
        bool active, bool acked, bool? confirmed, AlarmShelveState shelve, bool suppressed, int severity) =>
        new(Active: active, Acknowledged: acked, Confirmed: confirmed,
@@ -26,6 +35,11 @@ public static class OpcUaAlarmMapper
    /// Acknowledgement takes precedence over an active/inactive edge when both
    /// change in the same event; an unchanged event is reported as a StateChange.
    /// </summary>
+    /// <param name="prevAcked">Acknowledged state before the event.</param>
+    /// <param name="nowAcked">Acknowledged state after the event.</param>
+    /// <param name="prevActive">Active state before the event.</param>
+    /// <param name="nowActive">Active state after the event.</param>
+    /// <returns>The <see cref="AlarmTransitionKind"/> that best describes the state change.</returns>
    public static AlarmTransitionKind DeriveKind(bool prevAcked, bool nowAcked, bool prevActive, bool nowActive)
    {
        if (!prevAcked && nowAcked)
@@ -40,6 +54,8 @@ public static class OpcUaAlarmMapper
    }

    /// <summary>Maps the OPC UA ShelvingState current-state node name to the shelve enum.</summary>
+    /// <param name="shelvingStateName">The OPC UA ShelvingState node name, or null when unshelved.</param>
+    /// <returns>The corresponding <see cref="AlarmShelveState"/>; defaults to <see cref="AlarmShelveState.Unshelved"/>.</returns>
    public static AlarmShelveState MapShelve(string? shelvingStateName) => shelvingStateName switch
    {
        "OneShotShelved" => AlarmShelveState.OneShotShelved,
@@ -339,6 +339,7 @@ public class OpcUaDataConnection : IDataConnection, IBrowsableDataConnection, IA
    /// <summary>
    /// Asynchronously disposes the OPC UA connection, releasing the client and stopping the heartbeat monitor.
    /// </summary>
+    /// <returns>A <see cref="ValueTask"/> that completes when the client has been released and the heartbeat monitor stopped.</returns>
    public async ValueTask DisposeAsync()
    {
        StopHeartbeatMonitor();
@@ -301,7 +301,10 @@ public sealed class RealMxGatewayClient : IMxGatewayClient
        }
    }

-    /// <inheritdoc />
+    /// <summary>
+    /// Asynchronously disposes the active MxAccess session, client, and galaxy resources.
+    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    public async ValueTask DisposeAsync()
    {
        if (_session is not null) await _session.DisposeAsync().ConfigureAwait(false);