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).

tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Tests/Backend/AahClientManagedAlarmEventWriterTests.cs

@@ -22,6 +22,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Tests
     public sealed class AahClientManagedAlarmEventWriterTests
     {
         /// <summary>Verifies that an empty batch returns an empty array without invoking the backend.</summary>
+        /// <returns>A task that represents the asynchronous operation.</returns>
         [Fact]
         public async Task Empty_batch_returns_empty_array_without_invoking_backend()
         {
@@ -35,6 +36,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Tests
         }
 
         /// <summary>Verifies that a single acknowledgment outcome maps to true.</summary>
+        /// <returns>A task that represents the asynchronous operation.</returns>
         [Fact]
         public async Task Single_ack_outcome_maps_to_true()
         {
@@ -47,6 +49,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Tests
         }
 
         /// <summary>Verifies that a mixed batch preserves per-slot outcome ordering.</summary>
+        /// <returns>A task that represents the asynchronous operation.</returns>
         [Fact]
         public async Task Mixed_batch_preserves_per_slot_ordering()
         {
@@ -69,6 +72,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Tests
         }
 
         /// <summary>Verifies that backend exceptions mark the whole batch as RetryPlease.</summary>
+        /// <returns>A task that represents the asynchronous operation.</returns>
         [Fact]
         public async Task Backend_exception_marks_whole_batch_RetryPlease()
         {
@@ -85,6 +89,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Tests
         }
 
         /// <summary>Verifies that cancellation propagates from the backend.</summary>
+        /// <returns>A task that represents the asynchronous operation.</returns>
         [Fact]
         public async Task Cancellation_propagates_from_backend()
         {
@@ -97,6 +102,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Tests
         }
 
         /// <summary>Verifies that a backend returning the wrong outcome count degrades to RetryPlease.</summary>
+        /// <returns>A task that represents the asynchronous operation.</returns>
         [Fact]
         public async Task Backend_returning_wrong_count_degrades_to_RetryPlease()
         {
@@ -116,6 +122,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Tests
 
         /// <summary>Verifies that a large batch with all acknowledgments returns all true outcomes.</summary>
         /// <param name="batchSize">The batch size to test.</param>
+        /// <returns>A task that represents the asynchronous operation.</returns>
         [Theory]
         [InlineData(100)]
         [InlineData(1000)]
@@ -139,6 +146,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Tests
 
         /// <summary>Verifies that a large batch with alternating outcomes preserves positional ordering.</summary>
         /// <param name="batchSize">The batch size to test.</param>
+        /// <returns>A task that represents the asynchronous operation.</returns>
         [Theory]
         [InlineData(100)]
         [InlineData(1000)]
@@ -165,6 +173,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Tests
         }
 
         /// <summary>Verifies that retry then succeed correctly simulates cluster failover.</summary>
+        /// <returns>A task that represents the asynchronous operation.</returns>
         [Fact]
         public async Task Backend_retry_then_succeed_simulates_cluster_failover()
         {
@@ -255,10 +264,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Tests
                 _produce = produce;
             }
 
-            /// <summary>Records a call and returns outcomes from the delegate.</summary>
-            /// <param name="events">The events to write.</param>
-            /// <param name="cancellationToken">Cancellation token.</param>
-            /// <returns>The outcomes produced by the delegate.</returns>
+            /// <inheritdoc />
             public Task<AlarmHistorianWriteOutcome[]> WriteBatchAsync(
                 AlarmHistorianEventDto[] events, CancellationToken cancellationToken)
             {

tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Tests/Backend/HistorianDataSourceConnectFailoverTests.cs

@@ -19,6 +19,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Tests.Backend;
 public sealed class HistorianDataSourceConnectFailoverTests
 {
     /// <summary>Verifies that ReadRaw throws when no nodes are healthy.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task ReadRaw_when_no_nodes_are_healthy_throws_so_IPC_surfaces_Success_false()
     {
@@ -45,6 +46,7 @@ public sealed class HistorianDataSourceConnectFailoverTests
     }
 
     /// <summary>Verifies that ReadRaw tries each cluster node in order.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task ReadRaw_tries_each_cluster_node_in_order_until_one_succeeds_or_all_fail()
     {
@@ -71,6 +73,7 @@ public sealed class HistorianDataSourceConnectFailoverTests
     }
 
     /// <summary>Verifies that failed nodes are marked in cooldown and not retried immediately.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task ReadRaw_marks_failed_nodes_in_cooldown_so_a_subsequent_call_sees_no_healthy_nodes()
     {
@@ -96,6 +99,7 @@ public sealed class HistorianDataSourceConnectFailoverTests
     }
 
     /// <summary>Verifies that ReadEvents uses a separate event connection path.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task ReadEvents_uses_a_separate_event_connection_path()
     {
@@ -131,6 +135,7 @@ public sealed class HistorianDataSourceConnectFailoverTests
         /// <param name="config">The historian configuration.</param>
         /// <param name="type">The connection type.</param>
         /// <param name="readOnly">Whether to open a read-only connection.</param>
+        /// <returns>Never returns; always throws <see cref="InvalidOperationException"/>.</returns>
         public HistorianAccess CreateAndConnect(
             HistorianConfiguration config, HistorianConnectionType type, bool readOnly = true)
             => throw new InvalidOperationException($"simulated connect failure to {config.ServerName}");
@@ -149,6 +154,7 @@ public sealed class HistorianDataSourceConnectFailoverTests
         /// <param name="config">The historian configuration.</param>
         /// <param name="type">The connection type.</param>
         /// <param name="readOnly">Whether to open a read-only connection.</param>
+        /// <returns>Never returns; always throws <see cref="InvalidOperationException"/>.</returns>
         public HistorianAccess CreateAndConnect(
             HistorianConfiguration config, HistorianConnectionType type, bool readOnly = true)
         {

tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Tests/Backend/HistorianDataSourceRequestTimeoutTests.cs

@@ -65,6 +65,7 @@ public sealed class HistorianDataSourceRequestTimeoutTests
     }
 
     /// <summary>Verifies short timeout values correctly fire cancellation on the linked token.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task Small_timeout_cancels_the_linked_token()
     {

tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Tests/Backend/SdkAlarmHistorianWriteBackendTests.cs

@@ -27,6 +27,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Tests
         // ── Connection-unavailable path (deterministic, no SDK load) ──────────
 
         /// <summary>Verifies that an empty batch returns an empty outcome array.</summary>
+        /// <returns>A task that represents the asynchronous operation.</returns>
         [Fact]
         public async Task Empty_batch_returns_empty_array()
         {
@@ -40,6 +41,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Tests
         }
 
         /// <summary>Verifies that when all nodes are unreachable, the entire batch is deferred as RetryPlease.</summary>
+        /// <returns>A task that represents the asynchronous operation.</returns>
         [Fact]
         public async Task Unreachable_node_defers_whole_batch_as_RetryPlease()
         {
@@ -57,6 +59,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Tests
         }
 
         /// <summary>Verifies that a large batch with unreachable nodes returns one outcome per event.</summary>
+        /// <returns>A task that represents the asynchronous operation.</returns>
         [Fact]
         public async Task Unreachable_node_large_batch_returns_one_outcome_per_event()
         {
@@ -73,6 +76,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Tests
         }
 
         /// <summary>Verifies that a connection failure marks the node as failed in the endpoint picker.</summary>
+        /// <returns>A task that represents the asynchronous operation.</returns>
         [Fact]
         public async Task Connect_failure_marks_node_failed_in_picker()
         {
@@ -229,6 +233,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Tests
         // these need a live AVEVA Historian and are un-skipped during the PR D.1 smoke.
 
         /// <summary>Verifies that a single alarm event roundtrip returns an Ack outcome.</summary>
+        /// <returns>A task that represents the asynchronous operation.</returns>
         [Fact(Skip = "rig-required: needs a live AVEVA Historian — un-skip during the PR D.1 rollout smoke")]
         public async Task Live_single_event_roundtrip_returns_Ack()
         {
@@ -241,6 +246,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Tests
         }
 
         /// <summary>Verifies that cluster failover rotates from a bad primary node to a secondary node.</summary>
+        /// <returns>A task that represents the asynchronous operation.</returns>
         [Fact(Skip = "rig-required: needs a live AVEVA Historian cluster (two nodes) — un-skip during the PR D.1 rollout smoke")]
         public async Task Live_cluster_failover_primary_bad_rotates_to_secondary()
         {
@@ -311,10 +317,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host.Tests
         /// </summary>
         private sealed class ThrowingConnectionFactory : IHistorianConnectionFactory
         {
-            /// <summary>Creates and attempts to connect, always throwing a simulated connect failure.</summary>
-            /// <param name="config">The historian configuration specifying the target server.</param>
-            /// <param name="type">The connection type (Process or Event).</param>
-            /// <param name="readOnly">Whether to open a read-only connection.</param>
+            /// <inheritdoc />
             public HistorianAccess CreateAndConnect(
                 HistorianConfiguration config, HistorianConnectionType type, bool readOnly = true)
                 => throw new InvalidOperationException($"simulated connect failure to {config.ServerName}");