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
@@ -34,6 +34,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests;
 public sealed class TwinCAT3SmokeTests(TwinCATXarFixture sim)
 {
    /// <summary>Verifies that the driver reads a seeded DINT value through real ADS.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [TwinCATFact]
    public async Task Driver_reads_seeded_DINT_through_real_ADS()
    {
@@ -56,6 +57,7 @@ public sealed class TwinCAT3SmokeTests(TwinCATXarFixture sim)
    }

    /// <summary>Verifies a write-then-read round trip on a scratch REAL variable.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [TwinCATFact]
    public async Task Driver_write_then_read_round_trip_on_scratch_REAL()
    {
@@ -80,6 +82,7 @@ public sealed class TwinCAT3SmokeTests(TwinCATXarFixture sim)
    }

    /// <summary>Verifies that the driver receives native ADS notifications on counter value changes.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [TwinCATFact]
    public async Task Driver_subscribe_receives_native_ADS_notifications_on_counter_changes()
    {
@@ -117,6 +120,7 @@ public sealed class TwinCAT3SmokeTests(TwinCATXarFixture sim)
    }

    /// <summary>Verifies that the driver browses the committed symbol hierarchy via real ADS.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [TwinCATFact]
    public async Task Driver_browses_committed_symbol_hierarchy_via_real_ADS()
    {
@@ -158,6 +162,7 @@ public sealed class TwinCAT3SmokeTests(TwinCATXarFixture sim)
    }

    /// <summary>Verifies that the driver round-trips array element write and read operations.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [TwinCATFact]
    public async Task Driver_round_trips_array_element_write_and_read()
    {
@@ -185,6 +190,7 @@ public sealed class TwinCAT3SmokeTests(TwinCATXarFixture sim)
    }

    /// <summary>Verifies that the driver auto-reconnects after the underlying ADS client is disposed.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [TwinCATFact]
    public async Task Driver_auto_reconnects_after_underlying_client_is_disposed()
    {
@@ -215,6 +221,7 @@ public sealed class TwinCAT3SmokeTests(TwinCATXarFixture sim)
    /// <param name="symbolPath">The TwinCAT symbol path to read.</param>
    /// <param name="type">The TwinCAT data type of the symbol.</param>
    /// <param name="expectedValueInvariant">The expected value in culture-invariant format, or null to skip value assertion.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [TwinCATTheory]
    // vBool's expected value is null — the initial TRUE seed doesn't reliably survive cold
    // restarts on this deployment, and the point of this theory is round-tripping the type
@@ -296,6 +303,7 @@ public sealed class TwinCAT3SmokeTests(TwinCATXarFixture sim)
    }

    /// <summary>Verifies that the driver reads bit-indexed BOOL values from word symbols.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [TwinCATFact]
    public async Task Driver_reads_bit_indexed_BOOL_from_word()
    {
@@ -335,6 +343,7 @@ public sealed class TwinCAT3SmokeTests(TwinCATXarFixture sim)
    }

    /// <summary>Verifies that the driver reads deeply nested UDT member paths.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [TwinCATFact]
    public async Task Driver_reads_deeply_nested_UDT_path()
    {
@@ -373,6 +382,7 @@ public sealed class TwinCAT3SmokeTests(TwinCATXarFixture sim)
    }

    /// <summary>Verifies that the driver reports errors for unknown tags, nonexistent symbols, and read-only writes.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [TwinCATFact]
    public async Task Driver_reports_errors_for_unknown_tag_and_nonexistent_symbol_and_readonly_write()
    {
@@ -424,6 +434,7 @@ public sealed class TwinCAT3SmokeTests(TwinCATXarFixture sim)
    }

    /// <summary>Verifies that the driver routes reads per device and isolates unreachable peers.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [TwinCATFact]
    public async Task Driver_routes_reads_per_device_and_isolates_unreachable_peers()
    {
@@ -476,6 +487,7 @@ public sealed class TwinCAT3SmokeTests(TwinCATXarFixture sim)
    }

    /// <summary>Verifies that the probe loop raises a host status transition to Running when the target is reachable.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [TwinCATFact]
    public async Task Probe_loop_raises_host_status_transition_to_Running_on_reachable_target()
    {
@@ -520,6 +532,7 @@ public sealed class TwinCAT3SmokeTests(TwinCATXarFixture sim)
    }

    /// <summary>Verifies that DiscoverAsync renders declared tags and controller browse symbols to the address space builder.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [TwinCATFact]
    public async Task DiscoverAsync_renders_declared_tags_and_controller_browse_hits_address_space_builder()
    {
@@ -609,47 +622,34 @@ internal sealed class RecordingAddressSpaceBuilder : IAddressSpaceBuilder
    /// <summary>Gets the browse names of all recorded folders.</summary>
    public IEnumerable<string> FolderBrowseNames => Folders.Select(f => f.BrowseName);

-    /// <summary>Records a folder call and returns this builder for chaining.</summary>
-    /// <param name="browseName">The browse name of the folder.</param>
-    /// <param name="displayName">The display name of the folder.</param>
-    /// <returns>This builder instance for method chaining.</returns>
+    /// <inheritdoc />
    public IAddressSpaceBuilder Folder(string browseName, string displayName)
    {
        Folders.Add((browseName, displayName));
        return this;
    }

-    /// <summary>Records a variable call and returns a handle for it.</summary>
-    /// <param name="browseName">The browse name of the variable.</param>
-    /// <param name="displayName">The display name of the variable.</param>
-    /// <param name="info">The driver attribute information.</param>
-    /// <returns>A variable handle for the recorded variable.</returns>
+    /// <inheritdoc />
    public IVariableHandle Variable(string browseName, string displayName, DriverAttributeInfo info)
    {
        Variables.Add((browseName, info));
        return new Handle(info.FullName);
    }

-    /// <summary>Records a property call (no-op in this test double).</summary>
-    /// <param name="name">The property name.</param>
-    /// <param name="type">The property data type.</param>
-    /// <param name="value">The property value.</param>
+    /// <inheritdoc />
    public void AddProperty(string name, DriverDataType type, object? value) { }

    private sealed class Handle(string fullRef) : IVariableHandle
    {
-        /// <summary>Gets the full reference of the variable.</summary>
+        /// <inheritdoc />
        public string FullReference => fullRef;
-        /// <summary>Marks the variable as an alarm condition with the specified information.</summary>
-        /// <param name="info">Alarm condition information.</param>
-        /// <returns>An alarm condition sink for handling transitions.</returns>
+        /// <inheritdoc />
        public IAlarmConditionSink MarkAsAlarmCondition(AlarmConditionInfo info) => new NullSink();
    }

    private sealed class NullSink : IAlarmConditionSink
    {
-        /// <summary>Handles an alarm condition transition (no-op in this test double).</summary>
-        /// <param name="args">The alarm event arguments.</param>
+        /// <inheritdoc />
        public void OnTransition(AlarmEventArgs args) { }
    }
 }
@@ -87,14 +87,17 @@ public sealed class TwinCATXarFixture : IAsyncLifetime
        }
    }

-    /// <inheritdoc />
+    /// <summary>Initializes the fixture asynchronously (no-op for this fixture).</summary>
+    /// <returns>A completed value task.</returns>
    public ValueTask InitializeAsync() => ValueTask.CompletedTask;
-    /// <inheritdoc />
+    /// <summary>Disposes the fixture asynchronously (no-op for this fixture).</summary>
+    /// <returns>A completed value task.</returns>
    public ValueTask DisposeAsync() => ValueTask.CompletedTask;

    /// <summary><c>true</c> when the XAR runtime is reachable + the AmsNetId is set.
    /// Used by the skip attributes to avoid spinning up the fixture for every test
    /// class.</summary>
+    /// <returns><c>true</c> if the runtime is available; otherwise <c>false</c>.</returns>
    public static bool IsRuntimeAvailable()
    {
        if (string.IsNullOrWhiteSpace(Environment.GetEnvironmentVariable(NetIdEnvVar))) return false;