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];
     }
 }