docs: backfill XML documentation across 756 files

Adds <summary>, <param>, <typeparam>, and <inheritdoc/> tags to public
members surfaced by commentchecker — resolves 5,847 of 5,869 issues
(99.6%) across three /fixdocs passes.

tests/Core/ZB.MOM.WW.OtOpcUa.Core.AlarmHistorian.Tests/SqliteStoreAndForwardSinkTests.cs

@@ -19,12 +19,14 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
     private readonly string _dbPath;
     private readonly ILogger _log;
 
+    /// <summary>Initializes a new test instance.</summary>
     public SqliteStoreAndForwardSinkTests()
     {
         _dbPath = Path.Combine(Path.GetTempPath(), $"otopcua-historian-{Guid.NewGuid():N}.sqlite");
         _log = new LoggerConfiguration().MinimumLevel.Verbose().CreateLogger();
     }
 
+    /// <summary>Cleans up test resources.</summary>
     public void Dispose()
     {
         try { if (File.Exists(_dbPath)) File.Delete(_dbPath); } catch { }
@@ -32,11 +34,19 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
 
     private sealed class FakeWriter : IAlarmHistorianWriter
     {
+        /// <summary>Gets the queue of outcomes per event.</summary>
         public Queue<HistorianWriteOutcome> NextOutcomePerEvent { get; } = new();
+        /// <summary>Gets or sets the default outcome for events.</summary>
         public HistorianWriteOutcome DefaultOutcome { get; set; } = HistorianWriteOutcome.Ack;
+        /// <summary>Gets the batches that have been written.</summary>
         public List<IReadOnlyList<AlarmHistorianEvent>> Batches { get; } = [];
+        /// <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>
         public Task<IReadOnlyList<HistorianWriteOutcome>> WriteBatchAsync(
             IReadOnlyList<AlarmHistorianEvent> batch, CancellationToken ct)
         {
@@ -66,6 +76,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
         Comment: null,
         TimestampUtc: ts ?? DateTime.UtcNow);
 
+    /// <summary>Verifies that acknowledged events are removed from the queue.</summary>
     [Fact]
     public async Task EnqueueThenDrain_Ack_removes_row()
     {
@@ -86,6 +97,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
         status.LastSuccessUtc.ShouldNotBeNull();
     }
 
+    /// <summary>Verifies that draining an empty queue is a no-op.</summary>
     [Fact]
     public async Task Drain_with_empty_queue_is_noop()
     {
@@ -98,6 +110,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
         sink.GetStatus().DrainState.ShouldBe(HistorianDrainState.Idle);
     }
 
+    /// <summary>Verifies that RetryPlease outcome bumps backoff and keeps the row queued.</summary>
     [Fact]
     public async Task RetryPlease_bumps_backoff_and_keeps_row()
     {
@@ -114,6 +127,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
         sink.GetStatus().DrainState.ShouldBe(HistorianDrainState.BackingOff);
     }
 
+    /// <summary>Verifies that an Ack after RetryPlease resets backoff to the floor.</summary>
     [Fact]
     public async Task Ack_after_Retry_resets_backoff()
     {
@@ -132,6 +146,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
         sink.GetStatus().QueueDepth.ShouldBe(0);
     }
 
+    /// <summary>Verifies that PermanentFail outcome dead-letters only the failed event.</summary>
     [Fact]
     public async Task PermanentFail_dead_letters_one_row_only()
     {
@@ -149,6 +164,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
         status.DeadLetterDepth.ShouldBe(1, "bad row dead-lettered");
     }
 
+    /// <summary>Verifies that writer exceptions trigger retry for the entire batch.</summary>
     [Fact]
     public async Task Writer_exception_treated_as_retry_for_whole_batch()
     {
@@ -168,6 +184,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
         sink.GetStatus().QueueDepth.ShouldBe(0);
     }
 
+    /// <summary>Verifies that capacity eviction drops the oldest non-dead-lettered row.</summary>
     [Fact]
     public async Task Capacity_eviction_drops_oldest_nondeadlettered_row()
     {
@@ -191,6 +208,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
         drained.ShouldContain("A4");
     }
 
+    /// <summary>Verifies that dead-lettered rows are purged after retention period expires.</summary>
     [Fact]
     public async Task Deadlettered_rows_are_purged_past_retention()
     {
@@ -214,6 +232,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
         sink.GetStatus().DeadLetterDepth.ShouldBe(0, "purged past retention");
     }
 
+    /// <summary>Verifies that RetryDeadLettered requeues dead-lettered rows for retry.</summary>
     [Fact]
     public async Task RetryDeadLettered_requeues_for_retry()
     {
@@ -233,6 +252,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
         status.DeadLetterDepth.ShouldBe(0);
     }
 
+    /// <summary>Verifies that the exponential backoff ladder caps at 60 seconds.</summary>
     [Fact]
     public async Task Backoff_ladder_caps_at_60s()
     {
@@ -248,6 +268,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
         sink.CurrentBackoff.ShouldBe(TimeSpan.FromSeconds(60));
     }
 
+    /// <summary>Verifies that NullAlarmHistorianSink reports disabled status.</summary>
     [Fact]
     public void NullAlarmHistorianSink_reports_disabled_status()
     {
@@ -256,6 +277,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
         s.QueueDepth.ShouldBe(0);
     }
 
+    /// <summary>Verifies that NullAlarmHistorianSink silently swallows enqueue calls.</summary>
     [Fact]
     public async Task NullAlarmHistorianSink_swallows_enqueue()
     {
@@ -263,6 +285,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
         await NullAlarmHistorianSink.Instance.EnqueueAsync(Event("A1"), CancellationToken.None);
     }
 
+    /// <summary>Verifies that the constructor rejects invalid arguments.</summary>
     [Fact]
     public void Ctor_rejects_bad_args()
     {
@@ -274,6 +297,7 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
         Should.Throw<ArgumentOutOfRangeException>(() => new SqliteStoreAndForwardSink(_dbPath, w, _log, capacity: 0));
     }
 
+    /// <summary>Verifies that a disposed sink rejects enqueue operations.</summary>
     [Fact]
     public async Task Disposed_sink_rejects_enqueue()
     {
@@ -474,8 +498,13 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
     /// <summary>A writer that throws once, then behaves normally — used to prove the drain loop self-heals.</summary>
     private sealed class ThrowingThenHealingWriter : IAlarmHistorianWriter
     {
+        /// <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>
         public Task<IReadOnlyList<HistorianWriteOutcome>> WriteBatchAsync(
             IReadOnlyList<AlarmHistorianEvent> batch, CancellationToken ct)
         {
@@ -597,9 +626,16 @@ public sealed class SqliteStoreAndForwardSinkTests : IDisposable
     {
         private bool _returnExtra;
 
+        /// <summary>Initializes a new instance.</summary>
+        /// <param name="returnExtraOutcome">Whether to return an extra outcome on the first call.</param>
         public WrongCardinalityWriter(bool returnExtraOutcome) => _returnExtra = returnExtraOutcome;
+        /// <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>
         public Task<IReadOnlyList<HistorianWriteOutcome>> WriteBatchAsync(
             IReadOnlyList<AlarmHistorianEvent> batch, CancellationToken ct)
         {