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.OpcUaClient.Tests/OpcUaClientAlarmTests.cs

@@ -33,6 +33,7 @@ public sealed class OpcUaClientAlarmTests
     }
 
     /// <summary>Verifies that SubscribeAlarmsAsync without initialize throws InvalidOperationException.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task SubscribeAlarmsAsync_without_initialize_throws_InvalidOperationException()
     {
@@ -42,6 +43,7 @@ public sealed class OpcUaClientAlarmTests
     }
 
     /// <summary>Verifies that UnsubscribeAlarmsAsync with unknown handle is noop.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task UnsubscribeAlarmsAsync_with_unknown_handle_is_noop()
     {
@@ -51,6 +53,7 @@ public sealed class OpcUaClientAlarmTests
     }
 
     /// <summary>Verifies that AcknowledgeAsync without initialize throws InvalidOperationException.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task AcknowledgeAsync_without_initialize_throws_InvalidOperationException()
     {
@@ -62,6 +65,7 @@ public sealed class OpcUaClientAlarmTests
     }
 
     /// <summary>Verifies that AcknowledgeAsync with empty batch is noop even without init.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task AcknowledgeAsync_with_empty_batch_is_noop_even_without_init()
     {
@@ -73,7 +77,7 @@ public sealed class OpcUaClientAlarmTests
 
     private sealed class FakeAlarmHandle : IAlarmSubscriptionHandle
     {
-        /// <summary>Gets the diagnostic identifier for this alarm handle.</summary>
+        /// <inheritdoc />
         public string DiagnosticId => "fake-alarm";
     }
 }

tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Tests/OpcUaClientDiscoveryTests.cs

@@ -13,6 +13,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Tests;
 public sealed class OpcUaClientDiscoveryTests
 {
     /// <summary>Verifies that DiscoverAsync throws InvalidOperationException when not initialized.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task DiscoverAsync_without_initialize_throws_InvalidOperationException()
     {
@@ -44,22 +45,14 @@ public sealed class OpcUaClientDiscoveryTests
     /// <summary>Test builder that provides no-op implementations for discovery tests.</summary>
     private sealed class NullAddressSpaceBuilder : IAddressSpaceBuilder
     {
-        /// <summary>Returns this builder (no-op).</summary>
-        /// <param name="browseName">The browse name of the folder.</param>
-        /// <param name="displayName">The display name of the folder.</param>
+        /// <inheritdoc />
         public IAddressSpaceBuilder Folder(string browseName, string displayName) => this;
 
-        /// <summary>Returns a stub handle.</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>
+        /// <inheritdoc />
         public IVariableHandle Variable(string browseName, string displayName, DriverAttributeInfo attributeInfo)
             => new StubHandle();
 
-        /// <summary>No-op property addition.</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 property value.</param>
+        /// <inheritdoc />
         public void AddProperty(string browseName, DriverDataType dataType, object? value) { }
 
         /// <summary>No-op alarm condition attachment.</summary>
@@ -71,11 +64,10 @@ public sealed class OpcUaClientDiscoveryTests
         /// <summary>Stub variable handle for testing.</summary>
         private sealed class StubHandle : IVariableHandle
         {
-            /// <summary>Gets the full reference as "stub".</summary>
+            /// <inheritdoc />
             public string FullReference => "stub";
 
-            /// <summary>Throws NotSupportedException.</summary>
-            /// <param name="info">The alarm condition information (unused).</param>
+            /// <inheritdoc />
             public IAlarmConditionSink MarkAsAlarmCondition(AlarmConditionInfo info) => throw new NotSupportedException();
         }
     }

tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Tests/OpcUaClientDriverScaffoldTests.cs

@@ -45,6 +45,7 @@ public sealed class OpcUaClientDriverScaffoldTests
     }
 
     /// <summary>Verifies that Initialize against unreachable endpoint transitions to Faulted and throws.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Initialize_against_unreachable_endpoint_transitions_to_Faulted_and_throws()
     {
@@ -72,6 +73,7 @@ public sealed class OpcUaClientDriverScaffoldTests
     }
 
     /// <summary>Verifies that Reinitialize against unreachable endpoint re-throws the error.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Reinitialize_against_unreachable_endpoint_re_throws()
     {

tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Tests/OpcUaClientFailoverTests.cs

@@ -60,6 +60,7 @@ public sealed class OpcUaClientFailoverTests
     }
 
     /// <summary>Verifies that initializing against all unreachable endpoints throws AggregateException listing each.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Initialize_against_all_unreachable_endpoints_throws_AggregateException_listing_each()
     {

tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Tests/OpcUaClientHistoryTests.cs

@@ -34,6 +34,7 @@ public sealed class OpcUaClientHistoryTests
     }
 
     /// <summary>Verifies ReadRawAsync throws without initialization.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task ReadRawAsync_without_initialize_throws_InvalidOperationException()
     {
@@ -45,6 +46,7 @@ public sealed class OpcUaClientHistoryTests
     }
 
     /// <summary>Verifies ReadRawAsync with malformed NodeId returns empty result.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task ReadRawAsync_with_malformed_NodeId_returns_empty_result_not_throw()
     {
@@ -58,6 +60,7 @@ public sealed class OpcUaClientHistoryTests
     }
 
     /// <summary>Verifies ReadProcessedAsync throws without initialization.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task ReadProcessedAsync_without_initialize_throws_InvalidOperationException()
     {
@@ -70,6 +73,7 @@ public sealed class OpcUaClientHistoryTests
     }
 
     /// <summary>Verifies ReadAtTimeAsync throws without initialization.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task ReadAtTimeAsync_without_initialize_throws_InvalidOperationException()
     {
@@ -81,6 +85,7 @@ public sealed class OpcUaClientHistoryTests
     }
 
     /// <summary>Verifies ReadEventsAsync throws NotSupportedException as documented.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task ReadEventsAsync_throws_NotSupportedException_as_documented()
     {

tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Tests/OpcUaClientLowFindingsRegressionTests.cs

@@ -121,6 +121,7 @@ public sealed class OpcUaClientLowFindingsRegressionTests
     }
 
     /// <summary>Verifies that UnsubscribeAsync with unknown handle does not throw after the fix.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task UnsubscribeAsync_unknown_handle_does_not_throw_after_fix()
     {
@@ -132,6 +133,7 @@ public sealed class OpcUaClientLowFindingsRegressionTests
     }
 
     /// <summary>Verifies that UnsubscribeAlarmsAsync with unknown handle does not throw after the fix.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task UnsubscribeAlarmsAsync_unknown_handle_does_not_throw_after_fix()
     {
@@ -143,14 +145,14 @@ public sealed class OpcUaClientLowFindingsRegressionTests
     /// <summary>Fake subscription handle for testing.</summary>
     private sealed class FakeHandle : Core.Abstractions.ISubscriptionHandle
     {
-        /// <summary>Gets the diagnostic identifier for this handle.</summary>
+        /// <inheritdoc />
         public string DiagnosticId => "fake-sub";
     }
 
     /// <summary>Fake alarm subscription handle for testing.</summary>
     private sealed class FakeAlarmHandle : Core.Abstractions.IAlarmSubscriptionHandle
     {
-        /// <summary>Gets the diagnostic identifier for this handle.</summary>
+        /// <inheritdoc />
         public string DiagnosticId => "fake-alarm-sub";
     }
 }

tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Tests/OpcUaClientMediumFindingsRegressionTests.cs

@@ -23,6 +23,7 @@ public sealed class OpcUaClientMediumFindingsRegressionTests
     // ---- Driver.OpcUaClient-009 ----
 
     /// <summary>Verifies that WriteAsync without session returns BadCommunicationError, not BadTimeout.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task WriteAsync_without_session_returns_BadCommunicationError_not_BadTimeout()
     {
@@ -69,6 +70,7 @@ public sealed class OpcUaClientMediumFindingsRegressionTests
     }
 
     /// <summary>Verifies that InitializeAsync with AutoAccept emits a warning log.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task InitializeAsync_AutoAccept_emits_warning_log()
     {
@@ -108,6 +110,7 @@ public sealed class OpcUaClientMediumFindingsRegressionTests
     }
 
     /// <summary>Verifies that FlushOptionalCachesAsync completes without throwing.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task FlushOptionalCachesAsync_completes_without_throwing()
     {
@@ -118,6 +121,7 @@ public sealed class OpcUaClientMediumFindingsRegressionTests
     }
 
     /// <summary>Verifies that FlushOptionalCachesAsync resets the footprint counter.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task FlushOptionalCachesAsync_resets_footprint_counter()
     {

tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Tests/OpcUaClientReadWriteTests.cs

@@ -13,6 +13,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Tests;
 public sealed class OpcUaClientReadWriteTests
 {
     /// <summary>Verifies that ReadAsync throws InvalidOperationException when not initialized.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task ReadAsync_without_initialize_throws_InvalidOperationException()
     {
@@ -22,6 +23,7 @@ public sealed class OpcUaClientReadWriteTests
     }
 
     /// <summary>Verifies that WriteAsync throws InvalidOperationException when not initialized.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task WriteAsync_without_initialize_throws_InvalidOperationException()
     {

tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Tests/OpcUaClientSubscribeAndProbeTests.cs

@@ -14,6 +14,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Tests;
 public sealed class OpcUaClientSubscribeAndProbeTests
 {
     /// <summary>Verifies that subscribe without initialization throws InvalidOperationException.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task SubscribeAsync_without_initialize_throws_InvalidOperationException()
     {
@@ -23,6 +24,7 @@ public sealed class OpcUaClientSubscribeAndProbeTests
     }
 
     /// <summary>Verifies that unsubscribe with unknown handle is a no-op.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task UnsubscribeAsync_with_unknown_handle_is_noop()
     {