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/Core/ZB.MOM.WW.OtOpcUa.Core.Tests/Resilience/AlarmSurfaceInvokerTests.cs

@@ -11,6 +11,7 @@ public sealed class AlarmSurfaceInvokerTests
     private static readonly DriverResilienceOptions TierAOptions = new() { Tier = DriverTier.A };
 
     /// <summary>Verifies SubscribeAsync on an empty list returns empty without calling the driver.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task SubscribeAsync_EmptyList_ReturnsEmpty_WithoutDriverCall()
     {
@@ -24,6 +25,7 @@ public sealed class AlarmSurfaceInvokerTests
     }
 
     /// <summary>Verifies SubscribeAsync with no resolver routes through the default host.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task SubscribeAsync_SingleHost_RoutesThroughDefaultHost()
     {
@@ -38,6 +40,7 @@ public sealed class AlarmSurfaceInvokerTests
     }
 
     /// <summary>Verifies SubscribeAsync fans out correctly to multiple hosts based on resolver.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task SubscribeAsync_MultiHost_FansOutByResolvedHost()
     {
@@ -57,6 +60,7 @@ public sealed class AlarmSurfaceInvokerTests
     }
 
     /// <summary>Verifies AcknowledgeAsync does not retry on failure.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task AcknowledgeAsync_DoesNotRetry_OnFailure()
     {
@@ -70,6 +74,7 @@ public sealed class AlarmSurfaceInvokerTests
     }
 
     /// <summary>Verifies SubscribeAsync retries on transient failures.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task SubscribeAsync_Retries_Transient_Failures()
     {
@@ -87,6 +92,7 @@ public sealed class AlarmSurfaceInvokerTests
     ///     Verify by using a per-call resolver with two distinct hosts and checking which host
     ///     name reaches the driver's UnsubscribeAlarmsAsync.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task UnsubscribeAsync_Routes_Through_Same_Host_As_Subscribe()
     {
@@ -112,6 +118,7 @@ public sealed class AlarmSurfaceInvokerTests
     }
 
     /// <summary>Verifies UnsubscribeAsync with no resolver uses the default host.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task UnsubscribeAsync_SingleHost_UsesDefaultHost()
     {
@@ -158,10 +165,7 @@ public sealed class AlarmSurfaceInvokerTests
         /// <summary>Gets the source node IDs from the most recent SubscribeAlarmsAsync call.</summary>
         public IReadOnlyList<string> LastSubscribedIds { get; private set; } = [];
 
-        /// <summary>Subscribes to alarms.</summary>
-        /// <param name="sourceNodeIds">The source node IDs to subscribe to.</param>
-        /// <param name="cancellationToken">Cancellation token.</param>
-        /// <returns>An alarm subscription handle.</returns>
+        /// <inheritdoc />
         public Task<IAlarmSubscriptionHandle> SubscribeAlarmsAsync(
             IReadOnlyList<string> sourceNodeIds, CancellationToken cancellationToken)
         {
@@ -172,20 +176,14 @@ public sealed class AlarmSurfaceInvokerTests
             return Task.FromResult<IAlarmSubscriptionHandle>(new StubHandle($"h-{SubscribeCallCount}"));
         }
 
-        /// <summary>Unsubscribes from alarms.</summary>
-        /// <param name="handle">The subscription handle to unsubscribe.</param>
-        /// <param name="cancellationToken">Cancellation token.</param>
-        /// <returns>A completed task.</returns>
+        /// <inheritdoc />
         public Task UnsubscribeAlarmsAsync(IAlarmSubscriptionHandle handle, CancellationToken cancellationToken)
         {
             UnsubscribeCallCount++;
             return Task.CompletedTask;
         }
 
-        /// <summary>Acknowledges alarms.</summary>
-        /// <param name="acknowledgements">The alarm acknowledgements to process.</param>
-        /// <param name="cancellationToken">Cancellation token.</param>
-        /// <returns>A completed task.</returns>
+        /// <inheritdoc />
         public Task AcknowledgeAsync(
             IReadOnlyList<AlarmAcknowledgeRequest> acknowledgements, CancellationToken cancellationToken)
         {
@@ -194,7 +192,7 @@ public sealed class AlarmSurfaceInvokerTests
             return Task.CompletedTask;
         }
 
-        /// <summary>Occurs when an alarm event is raised.</summary>
+        /// <inheritdoc />
         public event EventHandler<AlarmEventArgs>? OnAlarmEvent { add { } remove { } }
     }
 
@@ -206,9 +204,7 @@ public sealed class AlarmSurfaceInvokerTests
     /// <param name="map">The map of source node IDs to host names.</param>
     private sealed class StubResolver(Dictionary<string, string> map) : IPerCallHostResolver
     {
-        /// <summary>Resolves the host for the given full reference.</summary>
-        /// <param name="fullReference">The full reference to resolve.</param>
-        /// <returns>The resolved host name.</returns>
+        /// <inheritdoc />
         public string ResolveHost(string fullReference) => map[fullReference];
     }
 }

tests/Core/ZB.MOM.WW.OtOpcUa.Core.Tests/Resilience/CapabilityInvokerTests.cs

@@ -14,6 +14,7 @@ public sealed class CapabilityInvokerTests
         new(builder, "drv-test", () => options);
 
     /// <summary>Verifies that the capability invoker returns the value from the call site.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task Read_ReturnsValue_FromCallSite()
     {
@@ -29,6 +30,7 @@ public sealed class CapabilityInvokerTests
     }
 
     /// <summary>Verifies that the capability invoker retries on transient failures.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task Read_Retries_OnTransientFailure()
     {
@@ -52,6 +54,7 @@ public sealed class CapabilityInvokerTests
     }
 
     /// <summary>Verifies that non-idempotent writes do not retry even when the policy has retries configured.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task Write_NonIdempotent_DoesNotRetry_EvenWhenPolicyHasRetries()
     {
@@ -85,6 +88,7 @@ public sealed class CapabilityInvokerTests
     }
 
     /// <summary>Verifies that idempotent writes retry when the policy has retries configured.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task Write_Idempotent_Retries_WhenPolicyHasRetries()
     {
@@ -116,6 +120,7 @@ public sealed class CapabilityInvokerTests
     }
 
     /// <summary>Verifies that writes do not retry when the policy has zero retries configured.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task Write_Default_DoesNotRetry_WhenPolicyHasZeroRetries()
     {
@@ -143,6 +148,7 @@ public sealed class CapabilityInvokerTests
     }
 
     /// <summary>Verifies that different hosts are honored independently in the resilience pipeline.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task Execute_HonorsDifferentHosts_Independently()
     {
@@ -161,6 +167,7 @@ public sealed class CapabilityInvokerTests
     ///     redundant options objects on the per-write hot path and creates a consistency hazard
     ///     where an Admin edit mid-call could observe two different snapshots.
     /// </summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task ExecuteWriteAsync_NonIdempotent_Snapshots_Options_Once_Per_Call()
     {
@@ -195,6 +202,7 @@ public sealed class CapabilityInvokerTests
     ///     two derived values (<c>with</c> base + <c>Resolve(Write)</c>) come from the same options
     ///     instance.
     /// </summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task ExecuteWriteAsync_NonIdempotent_Uses_Consistent_Options_Snapshot()
     {

tests/Core/ZB.MOM.WW.OtOpcUa.Core.Tests/Resilience/DriverResiliencePipelineBuilderTests.cs

@@ -13,6 +13,7 @@ public sealed class DriverResiliencePipelineBuilderTests
     private static readonly DriverResilienceOptions TierAOptions = new() { Tier = DriverTier.A };
 
     /// <summary>Verifies that read operations retry transient failures.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task Read_Retries_Transient_Failures()
     {
@@ -31,6 +32,7 @@ public sealed class DriverResiliencePipelineBuilderTests
     }
 
     /// <summary>Verifies that write operations do not retry on failure.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task Write_DoesNotRetry_OnFailure()
     {
@@ -53,6 +55,7 @@ public sealed class DriverResiliencePipelineBuilderTests
     }
 
     /// <summary>Verifies that alarm acknowledge operations do not retry on failure.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task AlarmAcknowledge_DoesNotRetry_OnFailure()
     {
@@ -115,6 +118,7 @@ public sealed class DriverResiliencePipelineBuilderTests
     }
 
     /// <summary>Verifies that a dead host does not open the breaker for a sibling host.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task DeadHost_DoesNotOpenBreaker_ForSiblingHost()
     {
@@ -146,6 +150,7 @@ public sealed class DriverResiliencePipelineBuilderTests
     }
 
     /// <summary>Verifies that the circuit breaker opens after the failure threshold on tier A.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task CircuitBreaker_Opens_AfterFailureThreshold_OnTierA()
     {
@@ -171,6 +176,7 @@ public sealed class DriverResiliencePipelineBuilderTests
     }
 
     /// <summary>Verifies that timeout cancels slow operations.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task Timeout_Cancels_SlowOperation()
     {
@@ -211,6 +217,7 @@ public sealed class DriverResiliencePipelineBuilderTests
     }
 
     /// <summary>Verifies that cancellation is not retried.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task Cancellation_IsNot_Retried()
     {
@@ -232,6 +239,7 @@ public sealed class DriverResiliencePipelineBuilderTests
     }
 
     /// <summary>Verifies that the tracker records failure on every retry.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task Tracker_RecordsFailure_OnEveryRetry()
     {
@@ -253,6 +261,7 @@ public sealed class DriverResiliencePipelineBuilderTests
     }
 
     /// <summary>Verifies that the tracker stamps the breaker open when it trips.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task Tracker_StampsBreakerOpen_WhenBreakerTrips()
     {
@@ -277,6 +286,7 @@ public sealed class DriverResiliencePipelineBuilderTests
     }
 
     /// <summary>Verifies that the tracker isolates counters per host.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task Tracker_IsolatesCounters_PerHost()
     {

tests/Core/ZB.MOM.WW.OtOpcUa.Core.Tests/Resilience/FlakeyDriverIntegrationTests.cs

@@ -15,6 +15,7 @@ namespace ZB.MOM.WW.OtOpcUa.Core.Tests.Resilience;
 public sealed class FlakeyDriverIntegrationTests
 {
     /// <summary>Verifies read succeeds after transient failures with retries.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task Read_SurfacesSuccess_AfterTransientFailures()
     {
@@ -43,6 +44,7 @@ public sealed class FlakeyDriverIntegrationTests
     }
 
     /// <summary>Verifies non-idempotent write fails on first failure without replay.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task Write_NonIdempotent_FailsOnFirstFailure_NoReplay()
     {
@@ -68,6 +70,7 @@ public sealed class FlakeyDriverIntegrationTests
     }
 
     /// <summary>Verifies idempotent write retries until success.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task Write_Idempotent_RetriesUntilSuccess()
     {
@@ -93,6 +96,7 @@ public sealed class FlakeyDriverIntegrationTests
     }
 
     /// <summary>Verifies multiple hosts have independent failure counts and circuit breakers.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task MultipleHosts_OnOneDriver_HaveIndependentFailureCounts()
     {
@@ -141,10 +145,7 @@ public sealed class FlakeyDriverIntegrationTests
             _failWritesBeforeIndex = failWritesBeforeIndex;
         }
 
-        /// <summary>Reads values, failing transiently until the threshold.</summary>
-        /// <param name="fullReferences">Full references to read.</param>
-        /// <param name="cancellationToken">Cancellation token.</param>
-        /// <returns>Data value snapshots.</returns>
+        /// <inheritdoc />
         public Task<IReadOnlyList<DataValueSnapshot>> ReadAsync(
             IReadOnlyList<string> fullReferences,
             CancellationToken cancellationToken)
@@ -160,10 +161,7 @@ public sealed class FlakeyDriverIntegrationTests
             return Task.FromResult(result);
         }
 
-        /// <summary>Writes values, failing transiently until the threshold.</summary>
-        /// <param name="writes">The write requests.</param>
-        /// <param name="cancellationToken">Cancellation token.</param>
-        /// <returns>Write results.</returns>
+        /// <inheritdoc />
         public Task<IReadOnlyList<WriteResult>> WriteAsync(
             IReadOnlyList<WriteRequest> writes,
             CancellationToken cancellationToken)

tests/Core/ZB.MOM.WW.OtOpcUa.Core.Tests/Resilience/InFlightCounterTests.cs

@@ -69,6 +69,7 @@ public sealed class InFlightCounterTests
     }
 
     /// <summary>Verifies that CapabilityInvoker increments the tracker during execution.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task CapabilityInvoker_IncrementsTracker_DuringExecution()
     {
@@ -97,6 +98,7 @@ public sealed class InFlightCounterTests
     }
 
     /// <summary>Verifies that CapabilityInvoker decrements the counter on exception.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task CapabilityInvoker_ExceptionPath_DecrementsCounter()
     {
@@ -119,6 +121,7 @@ public sealed class InFlightCounterTests
     }
 
     /// <summary>Verifies that CapabilityInvoker without a tracker does not throw.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task CapabilityInvoker_WithoutTracker_DoesNotThrow()
     {

tests/Core/ZB.MOM.WW.OtOpcUa.Core.Tests/Resilience/PerCallHostResolverDispatchTests.cs

@@ -22,13 +22,13 @@ public sealed class PerCallHostResolverDispatchTests
         /// <param name="map">The mapping of full references to host names.</param>
         public StaticResolver(Dictionary<string, string> map) => _map = map;
 
-        /// <summary>Resolves a host name from the static mapping.</summary>
-        /// <param name="fullReference">The full reference to resolve.</param>
+        /// <inheritdoc />
         public string ResolveHost(string fullReference) =>
             _map.TryGetValue(fullReference, out var host) ? host : string.Empty;
     }
 
     /// <summary>Verifies that a dead PLC does not open the breaker for healthy PLCs when using a per-call resolver.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task DeadPlc_DoesNotOpenBreaker_For_HealthyPlc_With_Resolver()
     {
@@ -80,6 +80,7 @@ public sealed class PerCallHostResolverDispatchTests
     }
 
     /// <summary>Verifies that without a resolver, the same host shares one resilience pipeline.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task WithoutResolver_SameHost_Shares_One_Pipeline()
     {
@@ -98,6 +99,7 @@ public sealed class PerCallHostResolverDispatchTests
     }
 
     /// <summary>Verifies that with a resolver, different hosts get separate resilience pipelines.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task WithResolver_TwoHosts_Get_Two_Pipelines()
     {