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
@@ -18,31 +18,21 @@ public sealed class S7DiscoveryAndSubscribeTests
        public readonly List<string> Folders = new();
        public readonly List<(string Name, DriverAttributeInfo Attr)> Variables = new();

-        /// <summary>Adds a folder to the address space.</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);
            return this;
        }

-        /// <summary>Adds a variable to the address space.</summary>
-        /// <param name="browseName">The browse name of the variable.</param>
-        /// <param name="displayName">The display name of the variable.</param>
-        /// <param name="attributeInfo">The attribute information for the variable.</param>
-        /// <returns>A handle to the created variable.</returns>
+        /// <inheritdoc />
        public IVariableHandle Variable(string browseName, string displayName, DriverAttributeInfo attributeInfo)
        {
            Variables.Add((browseName, attributeInfo));
            return new StubHandle();
        }

-        /// <summary>Adds a property to a variable.</summary>
-        /// <param name="browseName">The browse name of the property.</param>
-        /// <param name="dataType">The data type of the property.</param>
-        /// <param name="value">The initial value of the property.</param>
+        /// <inheritdoc />
        public void AddProperty(string browseName, DriverDataType dataType, object? value) { }

        /// <summary>Attaches an alarm condition to a variable.</summary>
@@ -53,18 +43,17 @@ public sealed class S7DiscoveryAndSubscribeTests

        private sealed class StubHandle : IVariableHandle
        {
-            /// <summary>Gets the full reference of the variable.</summary>
+            /// <inheritdoc />
            public string FullReference => "stub";

-            /// <summary>Marks this variable as an alarm condition.</summary>
-            /// <param name="info">The alarm condition information.</param>
-            /// <returns>An alarm condition sink.</returns>
+            /// <inheritdoc />
            public IAlarmConditionSink MarkAsAlarmCondition(AlarmConditionInfo info)
                => throw new NotImplementedException("S7 driver never calls this — no alarm surfacing");
        }
    }

    /// <summary>Verifies that DiscoverAsync projects every configured tag into the address space.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task DiscoverAsync_projects_every_tag_into_the_address_space()
    {
@@ -92,6 +81,7 @@ public sealed class S7DiscoveryAndSubscribeTests
    }

    /// <summary>Verifies that DiscoverAsync propagates the WriteIdempotent flag from tag configuration to attribute info.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task DiscoverAsync_propagates_WriteIdempotent_from_tag_to_attribute_info()
    {
@@ -127,6 +117,7 @@ public sealed class S7DiscoveryAndSubscribeTests
    }

    /// <summary>Verifies that SubscribeAsync returns unique handles and UnsubscribeAsync correctly accepts them.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task SubscribeAsync_returns_unique_handles_and_UnsubscribeAsync_accepts_them()
    {
@@ -151,6 +142,7 @@ public sealed class S7DiscoveryAndSubscribeTests
    }

    /// <summary>Verifies that Subscribe floors the publishing interval at 100ms.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Subscribe_publishing_interval_is_floored_at_100ms()
    {
@@ -18,6 +18,7 @@ public sealed class S7DriverCodeReviewFixTests

    /// <summary>Verifies that initialize rejects timer or counter tags with NotSupportedException.</summary>
    /// <param name="address">The S7 Timer or Counter address to test.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Theory]
    [InlineData("T0")]
    [InlineData("T15")]
@@ -48,6 +49,7 @@ public sealed class S7DriverCodeReviewFixTests
    }

    /// <summary>Verifies that initialize accepts DB and MIQ addresses without triggering the unsupported guard.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Initialize_accepts_DB_and_MIQ_addresses_without_the_unsupported_guard_tripping()
    {
@@ -75,6 +77,7 @@ public sealed class S7DriverCodeReviewFixTests
    // ---- Driver.S7-011 — driverConfigJson must be applied on Initialize ----

    /// <summary>Verifies that initialize applies the supplied driverConfigJson over constructor options.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Initialize_applies_the_supplied_driverConfigJson_over_the_constructor_options()
    {
@@ -101,6 +104,7 @@ public sealed class S7DriverCodeReviewFixTests
    }

    /// <summary>Verifies that initialize rejects a timer tag supplied only through driverConfigJson.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Initialize_rejects_a_timer_tag_supplied_only_through_driverConfigJson()
    {
@@ -120,6 +124,7 @@ public sealed class S7DriverCodeReviewFixTests
    }

    /// <summary>Verifies that reinitialize applies a changed driverConfigJson.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Reinitialize_applies_a_changed_driverConfigJson()
    {
@@ -142,6 +147,7 @@ public sealed class S7DriverCodeReviewFixTests
    // ---- Driver.S7-006 — Shutdown drains probe/poll loops before disposing the gate ----

    /// <summary>Verifies that shutdown completes cleanly with active subscriptions and no disposal race.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Shutdown_completes_cleanly_with_active_subscriptions_and_no_disposal_race()
    {
@@ -167,6 +173,7 @@ public sealed class S7DriverCodeReviewFixTests
    }

    /// <summary>Verifies that dispose after subscribe does not throw ObjectDisposedException.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Dispose_after_subscribe_does_not_throw_ObjectDisposedException()
    {
@@ -16,6 +16,7 @@ public sealed class S7DriverCodeReviewFixTests2
    // ── Driver.S7-003 — Read/WriteAsync must throw ArgumentNullException, not NRE ─────────

    /// <summary>Verifies that ReadAsync throws ArgumentNullException for null references.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task ReadAsync_with_null_fullReferences_throws_ArgumentNullException()
    {
@@ -28,6 +29,7 @@ public sealed class S7DriverCodeReviewFixTests2
    }

    /// <summary>Verifies that WriteAsync throws ArgumentNullException for null writes.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task WriteAsync_with_null_writes_throws_ArgumentNullException()
    {
@@ -39,6 +41,7 @@ public sealed class S7DriverCodeReviewFixTests2
    // ── Driver.S7-009 — Poll loop must update health on sustained failure ────────────────

    /// <summary>Verifies that the poll loop degrades health when the driver is uninitialized.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task PollLoop_against_uninitialized_driver_degrades_health()
    {
@@ -68,6 +71,7 @@ public sealed class S7DriverCodeReviewFixTests2
    }

    /// <summary>Verifies that the poll loop applies capped backoff after consecutive failures.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task PollLoop_applies_capped_backoff_after_consecutive_failures()
    {
@@ -140,6 +144,7 @@ public sealed class S7DriverCodeReviewFixTests2

    /// <summary>Verifies that Initialize rejects not-yet-implemented data types with NotSupportedException.</summary>
    /// <param name="dt">The S7 data type that is not yet implemented.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Theory]
    [InlineData(S7DataType.Int64)]
    [InlineData(S7DataType.UInt64)]
@@ -173,6 +178,7 @@ public sealed class S7DriverCodeReviewFixTests2
    /// <summary>Verifies that Initialize accepts implemented data types.</summary>
    /// <param name="dt">The S7 data type to test.</param>
    /// <param name="addr">The S7 address string corresponding to the data type.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Theory]
    [InlineData(S7DataType.Bool, "DB1.DBX0.0")]
    [InlineData(S7DataType.Byte, "DB1.DBB0")]
@@ -14,6 +14,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.S7.Tests;
 public sealed class S7DriverReadWriteTests
 {
    /// <summary>Verifies that initialization rejects invalid tag addresses and fails fast.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
    [Fact]
    public async Task Initialize_rejects_invalid_tag_address_and_fails_fast()
    {
@@ -36,6 +37,7 @@ public sealed class S7DriverReadWriteTests
    }

    /// <summary>Verifies that ReadAsync without initialize throws InvalidOperationException.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
    [Fact]
    public async Task ReadAsync_without_initialize_throws_InvalidOperationException()
    {
@@ -45,6 +47,7 @@ public sealed class S7DriverReadWriteTests
    }

    /// <summary>Verifies that WriteAsync without initialize throws InvalidOperationException.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
    [Fact]
    public async Task WriteAsync_without_initialize_throws_InvalidOperationException()
    {
@@ -53,6 +53,7 @@ public sealed class S7DriverScaffoldTests
    }

    /// <summary>Verifies that Initialize against unreachable host transitions to Faulted and throws.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Initialize_against_unreachable_host_transitions_to_Faulted_and_throws()
    {