docs: complete XML doc comments via fixdocs (2757 to 131 findings)

Add missing <returns>/<param>/<summary>/<typeparam> tags and clean up misused inheritdoc across 481 files so the documented API surface is complete. Documentation-only (zero code lines changed). The 131 remaining findings are inheritdoc-style warnings deliberately left to preserve hand-written implementation rationale (plan-decision notes, race-condition explanations).
2026-06-03 12:34:34 -04:00
parent c6d9b20d9f
commit bd6c0b4d3d
481 changed files with 2550 additions and 1668 deletions
@@ -74,6 +74,7 @@ public sealed class FocasSimFixture : IAsyncDisposable
    }

    /// <summary>Disposes the fixture and releases any held resources.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    public ValueTask DisposeAsync() => ValueTask.CompletedTask;

    // ---- Admin API helpers ----
@@ -85,23 +86,27 @@ public sealed class FocasSimFixture : IAsyncDisposable
    /// </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>
+    /// <returns>A task that resolves to the JSON response from the admin endpoint.</returns>
    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>
+    /// <returns>A task that resolves to the JSON response from the admin endpoint.</returns>
    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>
+    /// <returns>A task that resolves to the JSON response from the admin endpoint.</returns>
    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>
+    /// <returns>A task that resolves to the JSON response from the admin endpoint.</returns>
    public Task<JsonElement> ScheduleAlarmsAsync(IEnumerable<object> sequence, CancellationToken ct = default) =>
        SendAdminAsync("mock_schedule_alarms", new { sequence }, ct);

@@ -110,6 +115,7 @@ public sealed class FocasSimFixture : IAsyncDisposable
    /// <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>
+    /// <returns>A task that resolves to the JSON response from the admin endpoint.</returns>
    public async Task<JsonElement> SendAdminAsync(string method, object @params, CancellationToken ct = default)
    {
        using var client = new TcpClient();
@@ -26,6 +26,7 @@ public sealed class WireBackendCoverageTests
    private const string DeviceHost = "focas://127.0.0.1:8193";

    /// <summary>Verifies that user tag reads route via the wire backend.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
    [Fact]
    public async Task User_tag_reads_route_via_wire_backend()
    {
@@ -73,6 +74,7 @@ public sealed class WireBackendCoverageTests
    }

    /// <summary>Verifies that discover emits device folder and tag variables.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
    [Fact]
    public async Task Discover_emits_device_folder_and_tag_variables()
    {
@@ -107,6 +109,7 @@ public sealed class WireBackendCoverageTests
    }

    /// <summary>Verifies that subscribe fires OnDataChange via the wire backend.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
    [Fact]
    public async Task Subscribe_fires_OnDataChange_via_wire_backend()
    {
@@ -157,6 +160,7 @@ public sealed class WireBackendCoverageTests
    }

    /// <summary>Verifies that alarm raise then clear emits both events via the wire backend.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
    [Fact]
    public async Task Alarm_raise_then_clear_emits_both_events_via_wire_backend()
    {
@@ -210,6 +214,7 @@ public sealed class WireBackendCoverageTests
    }

    /// <summary>Verifies that the probe transitions to Running against the live mock.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
    [Fact]
    public async Task Probe_transitions_to_Running_against_live_mock()
    {
@@ -255,39 +260,29 @@ public sealed class WireBackendCoverageTests
        /// <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>
+        /// <inheritdoc />
        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>
+        /// <inheritdoc />
        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>
+        /// <inheritdoc />
        public void AddProperty(string _, DriverDataType __, object? ___) { }

        private sealed class Handle(string fullRef) : IVariableHandle
        {
-            /// <summary>Gets the full OPC UA reference for the variable.</summary>
+            /// <inheritdoc />
            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>
+            /// <inheritdoc />
            public IAlarmConditionSink MarkAsAlarmCondition(AlarmConditionInfo info) => new NullSink();
        }

        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>
+            /// <inheritdoc />
            public void OnTransition(AlarmEventArgs args) { }
        }
    }
@@ -29,6 +29,7 @@ public sealed class WireBackendTests
    private const string DeviceHost = "focas://127.0.0.1:8193";

    /// <summary>Verifies that identity axes and dynamic data populate via the wire backend.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Identity_axes_and_dynamic_populate_via_wire_backend()
    {
@@ -86,6 +87,7 @@ public sealed class WireBackendTests
    }

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

    /// <summary>Verifies that timer data populates via the wire backend.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Timers_populate_via_wire_backend()
    {
@@ -209,6 +212,7 @@ public sealed class WireBackendTests
    }

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