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.AlarmHistorian.Tests/SqliteStoreAndForwardSinkTests.cs

@@ -43,10 +43,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
         /// <summary>Gets or sets an exception to throw once.</summary>
         public Exception? ThrowOnce { get; set; }
 
-        /// <summary>Writes a batch of events.</summary>
-        /// <param name="batch">Events to write.</param>
-        /// <param name="ct">Cancellation token.</param>
-        /// <returns>A task returning the write outcomes.</returns>
+        /// <inheritdoc />
         public Task<IReadOnlyList<HistorianWriteOutcome>> WriteBatchAsync(
             IReadOnlyList<AlarmHistorianEvent> batch, CancellationToken ct)
         {
@@ -77,6 +74,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
         TimestampUtc: ts ?? DateTime.UtcNow);
 
     /// <summary>Verifies that acknowledged events are removed from the queue.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task EnqueueThenDrain_Ack_removes_row()
     {
@@ -98,6 +96,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
     }
 
     /// <summary>Verifies that draining an empty queue is a no-op.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Drain_with_empty_queue_is_noop()
     {
@@ -111,6 +110,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
     }
 
     /// <summary>Verifies that RetryPlease outcome bumps backoff and keeps the row queued.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task RetryPlease_bumps_backoff_and_keeps_row()
     {
@@ -128,6 +128,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
     }
 
     /// <summary>Verifies that an Ack after RetryPlease resets backoff to the floor.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Ack_after_Retry_resets_backoff()
     {
@@ -147,6 +148,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
     }
 
     /// <summary>Verifies that PermanentFail outcome dead-letters only the failed event.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task PermanentFail_dead_letters_one_row_only()
     {
@@ -165,6 +167,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
     }
 
     /// <summary>Verifies that writer exceptions trigger retry for the entire batch.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Writer_exception_treated_as_retry_for_whole_batch()
     {
@@ -185,6 +188,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
     }
 
     /// <summary>Verifies that capacity eviction drops the oldest non-dead-lettered row.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Capacity_eviction_drops_oldest_nondeadlettered_row()
     {
@@ -209,6 +213,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
     }
 
     /// <summary>Verifies that dead-lettered rows are purged after retention period expires.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Deadlettered_rows_are_purged_past_retention()
     {
@@ -233,6 +238,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
     }
 
     /// <summary>Verifies that RetryDeadLettered requeues dead-lettered rows for retry.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task RetryDeadLettered_requeues_for_retry()
     {
@@ -253,6 +259,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
     }
 
     /// <summary>Verifies that the exponential backoff ladder caps at 60 seconds.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Backoff_ladder_caps_at_60s()
     {
@@ -278,6 +285,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
     }
 
     /// <summary>Verifies that NullAlarmHistorianSink silently swallows enqueue calls.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task NullAlarmHistorianSink_swallows_enqueue()
     {
@@ -298,6 +306,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
     }
 
     /// <summary>Verifies that a disposed sink rejects enqueue operations.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Disposed_sink_rejects_enqueue()
     {
@@ -316,6 +325,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
     ///     forever), and every good row's outcome is applied to the CORRECT RowId —
     ///     no good event is silently lost.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Drain_with_corrupt_payload_row_deadletters_it_and_keeps_good_rows_aligned()
     {
@@ -347,6 +357,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
     ///     A corrupt row at the very head of the queue must be dead-lettered and not
     ///     prevent the good rows behind it from draining.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Drain_with_corrupt_head_row_does_not_stall_queue()
     {
@@ -373,6 +384,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
     ///     hammer the writer. We assert that after the backoff ladder advances, the
     ///     observed inter-batch gap actually grows beyond the bare tick interval.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task StartDrainLoop_honors_backoff_and_slows_cadence_under_retry()
     {
@@ -400,6 +412,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
     ///     steady cadence (backoff stays at the floor) — confirms the reschedule path
     ///     does not get stuck after a successful tick.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task StartDrainLoop_keeps_steady_cadence_when_writer_is_healthy()
     {
@@ -425,6 +438,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
     ///     be recorded into the status surface (LastError) and the drain loop must
     ///     keep rescheduling rather than silently dying.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task StartDrainLoop_records_drain_fault_and_keeps_running()
     {
@@ -454,6 +468,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
     ///     the busy_timeout + WAL pragmas in place the loser of the file-lock race
     ///     waits the lock out instead of failing fast.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Concurrent_enqueue_and_drain_do_not_throw_sqlite_busy()
     {
@@ -501,10 +516,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
         /// <summary>Gets the number of times WriteBatchAsync has been called.</summary>
         public int CallCount { get; private set; }
 
-        /// <summary>Writes a batch of events, throwing once then recovering.</summary>
-        /// <param name="batch">Events to write.</param>
-        /// <param name="ct">Cancellation token.</param>
-        /// <returns>A task returning the write outcomes.</returns>
+        /// <inheritdoc />
         public Task<IReadOnlyList<HistorianWriteOutcome>> WriteBatchAsync(
             IReadOnlyList<AlarmHistorianEvent> batch, CancellationToken ct)
         {
@@ -525,6 +537,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
     ///     by the timer callback, but still left the rows stranded on the first
     ///     cardinality-mismatched tick.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Writer_returning_wrong_cardinality_outcomes_sets_backing_off_and_keeps_rows()
     {
@@ -555,6 +568,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
     ///     evicted row count must be surfaced in <see cref="HistorianSinkStatus.EvictedCount"/>
     ///     so operators can detect bounded-durability overflow without log scraping.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Capacity_eviction_increments_evicted_count_on_status()
     {
@@ -580,6 +594,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
     ///     snapshot of all status fields — no torn DateTime? or stale DrainState.
     ///     Drive status writes from one thread and reads from another concurrently.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task GetStatus_snapshot_is_consistent_under_concurrent_drain()
     {
@@ -632,10 +647,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
         /// <summary>Fixes the writer to return correct cardinality.</summary>
         public void FixWriter() => _returnExtra = false;
 
-        /// <summary>Writes a batch of events, returning wrong cardinality until fixed.</summary>
-        /// <param name="batch">Events to write.</param>
-        /// <param name="ct">Cancellation token.</param>
-        /// <returns>A task returning the write outcomes.</returns>
+        /// <inheritdoc />
         public Task<IReadOnlyList<HistorianWriteOutcome>> WriteBatchAsync(
             IReadOnlyList<AlarmHistorianEvent> batch, CancellationToken ct)
         {
@@ -654,6 +666,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
     ///     capacity-probe count must stay bounded — not grow proportionally to the
     ///     enqueue count as the un-optimised path did.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task EnqueueAsync_does_not_count_all_rows_on_every_call_below_capacity()
     {
@@ -677,6 +690,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
     ///     stay aligned with a fresh <c>COUNT(*)</c> against the database. Catches drift
     ///     bugs in the in-memory counter introduced by the perf optimisation.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Enqueue_and_drain_keep_queue_depth_consistent_with_storage()
     {
@@ -724,6 +738,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
     ///     with storage. Catches drift bugs in the optimised path that would only show
     ///     up under contention.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Counter_remains_consistent_under_concurrent_enqueue_and_drain()
     {