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
@@ -21,6 +21,7 @@ public sealed class FocasDriverMediumFindingsTests
    // ---- Driver.FOCAS-003: unknown DeviceHostAddress fails at InitializeAsync ----

    /// <summary>Verifies that initialization throws when a tag references an undeclared device.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
    [Fact]
    public async Task InitializeAsync_throws_when_tag_DeviceHostAddress_not_in_Devices()
    {
@@ -43,6 +44,7 @@ public sealed class FocasDriverMediumFindingsTests
    }

    /// <summary>Verifies that initialization errors name the offending tag.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
    [Fact]
    public async Task InitializeAsync_throws_naming_the_offending_tag()
    {
@@ -64,6 +66,7 @@ public sealed class FocasDriverMediumFindingsTests
    }

    /// <summary>Verifies that initialization succeeds when all tags reference declared devices.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
    [Fact]
    public async Task InitializeAsync_succeeds_when_all_tags_reference_declared_devices()
    {
@@ -90,6 +93,7 @@ public sealed class FocasDriverMediumFindingsTests
    // ---- Driver.FOCAS-004: all FOCAS user tags advertised as ViewOnly ----

    /// <summary>Verifies that all user tags are advertised as ViewOnly regardless of Writable setting.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
    [Fact]
    public async Task DiscoverAsync_all_user_tags_are_ViewOnly_regardless_of_Writable_field()
    {
@@ -119,6 +123,7 @@ public sealed class FocasDriverMediumFindingsTests
    // ---- Driver.FOCAS-005: Volatile-guarded _health survives concurrent reads ----

    /// <summary>Verifies that GetHealth reflects state updated from concurrent reads.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
    [Fact]
    public async Task GetHealth_reflects_state_updated_from_concurrent_reads()
    {
@@ -148,6 +153,7 @@ public sealed class FocasDriverMediumFindingsTests
    // ---- Driver.FOCAS-006: EnsureConnectedAsync recreates a disposed/stale client ----

    /// <summary>Verifies that reads recover after client is externally disposed.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
    [Fact]
    public async Task Read_recovers_after_client_is_externally_disposed()
    {
@@ -184,6 +190,7 @@ public sealed class FocasDriverMediumFindingsTests
    }

    /// <summary>Verifies that reads dispose stale clients before creating fresh ones.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
    [Fact]
    public async Task Read_disposes_stale_client_before_creating_fresh_one()
    {
@@ -257,41 +264,31 @@ public sealed class FocasDriverMediumFindingsTests
        /// <summary>Gets or sets the list of added folders.</summary>
        public List<(string BrowseName, string DisplayName)> Folders { get; } = new();

-        /// <summary>Records a folder and returns this builder for chaining.</summary>
-        /// <param name="browseName">The OPC UA 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 and returns a handle for it.</summary>
-        /// <param name="browseName">The OPC UA browse name for the variable.</param>
-        /// <param name="displayName">The display name for the variable.</param>
-        /// <param name="info">The driver attribute information for the variable.</param>
+        /// <inheritdoc />
        public IVariableHandle Variable(string browseName, string displayName, DriverAttributeInfo info)
        { Variables.Add((browseName, info)); return new Handle(info.FullName); }

-        /// <summary>No-op property addition for test compatibility.</summary>
-        /// <param name="_">The property name (unused).</param>
-        /// <param name="__">The property data type (unused).</param>
-        /// <param name="___">The property value (unused).</param>
+        /// <inheritdoc />
        public void AddProperty(string _, DriverDataType __, object? ___) { }

        /// <summary>Test variable handle implementation.</summary>
        private sealed class Handle(string fullRef) : IVariableHandle
        {
-            /// <summary>Gets the full reference path of this variable.</summary>
+            /// <inheritdoc />
            public string FullReference => fullRef;

-            /// <summary>Marks this variable as an alarm condition and returns a sink for it.</summary>
-            /// <param name="info">The alarm condition information.</param>
+            /// <inheritdoc />
            public IAlarmConditionSink MarkAsAlarmCondition(AlarmConditionInfo info) => new NullSink();
        }

        /// <summary>No-op alarm condition sink for testing.</summary>
        private sealed class NullSink : IAlarmConditionSink
        {
-            /// <summary>Handles alarm condition transitions (no-op for testing).</summary>
-            /// <param name="args">The alarm event arguments.</param>
+            /// <inheritdoc />
            public void OnTransition(AlarmEventArgs args) { }
        }
    }