docs: backfill XML documentation across 756 files

Adds <summary>, <param>, <typeparam>, and <inheritdoc/> tags to public members surfaced by commentchecker — resolves 5,847 of 5,869 issues (99.6%) across three /fixdocs passes.
2026-05-28 08:10:17 -04:00
parent f9fc7dd2e1
commit 64e3fbe035
756 changed files with 9876 additions and 96 deletions
@@ -23,7 +23,10 @@ public sealed class FocasSimFixture : IAsyncDisposable
    private const string DefaultHost = "localhost";
    private const int DefaultPort = 8193;

+    /// <summary>Gets the hostname or IP address of the focas-mock simulator.</summary>
    public string Host { get; }
+
+    /// <summary>Gets the TCP port of the focas-mock simulator.</summary>
    public int Port { get; }

    /// <summary>focas-mock profile stem the fixture should load (e.g. <c>fwlib30i64</c>,
@@ -37,6 +40,10 @@ public sealed class FocasSimFixture : IAsyncDisposable
    /// <summary>Non-null when the mock probe failed — tests skip with this reason.</summary>
    public string? SkipReason { get; }

+    /// <summary>
+    ///     Initializes a new instance of the <see cref="FocasSimFixture"/> class by probing the focas-mock
+    ///     simulator endpoint. Reads the endpoint and profile from environment variables or uses defaults.
+    /// </summary>
    public FocasSimFixture()
    {
        var endpoint = Environment.GetEnvironmentVariable(EndpointEnvVar) ?? $"{DefaultHost}:{DefaultPort}";
@@ -66,6 +73,7 @@ public sealed class FocasSimFixture : IAsyncDisposable
        }
    }

+    /// <summary>Disposes the fixture and releases any held resources.</summary>
    public ValueTask DisposeAsync() => ValueTask.CompletedTask;

    // ---- Admin API helpers ----
@@ -75,23 +83,33 @@ public sealed class FocasSimFixture : IAsyncDisposable
    ///     (<c>fwlib30i64</c>) or the OtOpcUa-style alias (<c>ThirtyOne_i</c>);
    ///     focas-mock's <c>PROFILE_ALIASES</c> resolves both.
    /// </summary>
+    /// <param name="profileName">The DLL-stem name or OtOpcUa-style alias of the profile to load.</param>
+    /// <param name="ct">Cancellation token for the operation.</param>
    public Task<JsonElement> LoadProfileAsync(string profileName, CancellationToken ct = default) =>
        SendAdminAsync("mock_load_profile", new { profile = profileName }, ct);

    /// <summary>Deep-merge <paramref name="state"/> into the mock's current state.</summary>
+    /// <param name="state">The state object to deep-merge into the mock's current state.</param>
+    /// <param name="ct">Cancellation token for the operation.</param>
    public Task<JsonElement> PatchStateAsync(object state, CancellationToken ct = default) =>
        SendAdminAsync("mock_patch", new { state }, ct);

    /// <summary>Reset the mock to the selected profile's default state.</summary>
+    /// <param name="ct">Cancellation token for the operation.</param>
    public Task<JsonElement> ResetAsync(CancellationToken ct = default) =>
        SendAdminAsync("mock_reset", new { }, ct);

    /// <summary>Install a time-scheduled alarm raise / clear sequence.</summary>
+    /// <param name="sequence">The alarm sequence events to schedule.</param>
+    /// <param name="ct">Cancellation token for the operation.</param>
    public Task<JsonElement> ScheduleAlarmsAsync(IEnumerable<object> sequence, CancellationToken ct = default) =>
        SendAdminAsync("mock_schedule_alarms", new { sequence }, ct);

    /// <summary>Low-level JSON round-trip. One TCP connection per call — matches
    /// how the shim talks to the mock; simpler than pooling.</summary>
+    /// <param name="method">The admin method name to invoke.</param>
+    /// <param name="params">The parameters object to send with the request.</param>
+    /// <param name="ct">Cancellation token for the operation.</param>
    public async Task<JsonElement> SendAdminAsync(string method, object @params, CancellationToken ct = default)
    {
        using var client = new TcpClient();
@@ -19,10 +19,13 @@ public sealed class WireBackendCoverageTests
 {
    private readonly FocasSimFixture _fx;

+    /// <summary>Initializes a new instance of WireBackendCoverageTests with the FOCAS simulation fixture.</summary>
+    /// <param name="fx">The FOCAS simulation fixture.</param>
    public WireBackendCoverageTests(FocasSimFixture fx) => _fx = fx;

    private const string DeviceHost = "focas://127.0.0.1:8193";

+    /// <summary>Verifies that user tag reads route via the wire backend.</summary>
    [Fact]
    public async Task User_tag_reads_route_via_wire_backend()
    {
@@ -69,6 +72,7 @@ public sealed class WireBackendCoverageTests
        }
    }

+    /// <summary>Verifies that discover emits device folder and tag variables.</summary>
    [Fact]
    public async Task Discover_emits_device_folder_and_tag_variables()
    {
@@ -102,6 +106,7 @@ public sealed class WireBackendCoverageTests
        }
    }

+    /// <summary>Verifies that subscribe fires OnDataChange via the wire backend.</summary>
    [Fact]
    public async Task Subscribe_fires_OnDataChange_via_wire_backend()
    {
@@ -151,6 +156,7 @@ public sealed class WireBackendCoverageTests
        }
    }

+    /// <summary>Verifies that alarm raise then clear emits both events via the wire backend.</summary>
    [Fact]
    public async Task Alarm_raise_then_clear_emits_both_events_via_wire_backend()
    {
@@ -203,6 +209,7 @@ public sealed class WireBackendCoverageTests
        }
    }

+    /// <summary>Verifies that the probe transitions to Running against the live mock.</summary>
    [Fact]
    public async Task Probe_transitions_to_Running_against_live_mock()
    {
@@ -242,22 +249,46 @@ public sealed class WireBackendCoverageTests

    private sealed class RecordingBuilder : IAddressSpaceBuilder
    {
+        /// <summary>Gets the list of recorded folders.</summary>
        public List<(string BrowseName, string DisplayName)> Folders { get; } = new();
+
+        /// <summary>Gets the list of recorded variables.</summary>
        public List<(string BrowseName, DriverAttributeInfo Info)> Variables { get; } = new();

+        /// <summary>Records a folder in the address space builder.</summary>
+        /// <param name="browseName">The browse name for the folder.</param>
+        /// <param name="displayName">The display name for the folder.</param>
        public IAddressSpaceBuilder Folder(string browseName, string displayName)
        { Folders.Add((browseName, displayName)); return this; }

+        /// <summary>Records a variable in the address space builder.</summary>
+        /// <param name="browseName">The browse name for the variable.</param>
+        /// <param name="displayName">The display name for the variable.</param>
+        /// <param name="info">The driver attribute information.</param>
        public IVariableHandle Variable(string browseName, string displayName, DriverAttributeInfo info)
        { Variables.Add((browseName, info)); return new Handle(info.FullName); }

+        /// <summary>Records an address space property (no-op in this builder).</summary>
+        /// <param name="_">The property name.</param>
+        /// <param name="__">The property data type.</param>
+        /// <param name="___">The property value.</param>
        public void AddProperty(string _, DriverDataType __, object? ___) { }

        private sealed class Handle(string fullRef) : IVariableHandle
        {
+            /// <summary>Gets the full OPC UA reference for the variable.</summary>
            public string FullReference => fullRef;
+
+            /// <summary>Marks the variable as an alarm condition and returns a sink.</summary>
+            /// <param name="info">The alarm condition information.</param>
            public IAlarmConditionSink MarkAsAlarmCondition(AlarmConditionInfo info) => new NullSink();
        }
-        private sealed class NullSink : IAlarmConditionSink { public void OnTransition(AlarmEventArgs args) { } }
+
+        private sealed class NullSink : IAlarmConditionSink
+        {
+            /// <summary>Handles an alarm transition event (no-op in this sink).</summary>
+            /// <param name="args">The alarm event arguments.</param>
+            public void OnTransition(AlarmEventArgs args) { }
+        }
    }
 }
@@ -20,10 +20,15 @@ public sealed class WireBackendTests
 {
    private readonly FocasSimFixture _fx;

+    /// <summary>
+    /// Initializes a new instance of the <see cref="WireBackendTests"/> class.
+    /// </summary>
+    /// <param name="fx">The FOCAS simulator fixture.</param>
    public WireBackendTests(FocasSimFixture fx) => _fx = fx;

    private const string DeviceHost = "focas://127.0.0.1:8193";

+    /// <summary>Verifies that identity axes and dynamic data populate via the wire backend.</summary>
    [Fact]
    public async Task Identity_axes_and_dynamic_populate_via_wire_backend()
    {
@@ -80,6 +85,7 @@ public sealed class WireBackendTests
        }
    }

+    /// <summary>Verifies that program and operation mode data populate via the wire backend.</summary>
    [Fact]
    public async Task Program_and_operation_mode_populate_via_wire_backend()
    {
@@ -144,6 +150,7 @@ public sealed class WireBackendTests
        }
    }

+    /// <summary>Verifies that timer data populates via the wire backend.</summary>
    [Fact]
    public async Task Timers_populate_via_wire_backend()
    {
@@ -201,6 +208,7 @@ public sealed class WireBackendTests
        }
    }

+    /// <summary>Verifies that spindle load and max RPM data populate via the wire backend.</summary>
    [Fact]
    public async Task Spindle_load_and_max_rpm_populate_via_wire_backend()
    {