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.

src/Core/ZB.MOM.WW.OtOpcUa.Core.ScriptedAlarms/ScriptedAlarmEngine.cs

@@ -96,6 +96,7 @@ public sealed class ScriptedAlarmEngine : IDisposable
     ///     deterministic upstream push. Anything more involved should snapshot a
     ///     copy under the gate. (Core.ScriptedAlarms-013.)
     /// </remarks>
+    /// <param name="alarmId">The alarm identifier to look up.</param>
     internal IReadOnlyDictionary<string, DataValueSnapshot>? TryGetScratchReadCacheForTest(string alarmId)
         => _scratchByAlarmId.TryGetValue(alarmId, out var s) ? s.ReadCache : null;
 
@@ -111,6 +112,7 @@ public sealed class ScriptedAlarmEngine : IDisposable
     ///     for reference-identity assertions on a quiesced engine.
     ///     (Core.ScriptedAlarms-013.)
     /// </remarks>
+    /// <param name="alarmId">The alarm identifier to look up.</param>
     internal AlarmPredicateContext? TryGetScratchContextForTest(string alarmId)
         => _scratchByAlarmId.TryGetValue(alarmId, out var s) ? s.Context : null;
     private readonly ConcurrentDictionary<string, DataValueSnapshot> _valueCache
@@ -133,6 +135,15 @@ public sealed class ScriptedAlarmEngine : IDisposable
     private readonly HashSet<Task> _inFlight = [];
     private readonly object _inFlightLock = new();
 
+    /// <summary>
+    /// Initializes a new ScriptedAlarmEngine with the provided dependencies.
+    /// </summary>
+    /// <param name="upstream">The upstream tag source for reading tag values.</param>
+    /// <param name="store">The alarm state store for persistence.</param>
+    /// <param name="loggerFactory">The factory for creating alarm loggers.</param>
+    /// <param name="engineLogger">The logger for engine-level diagnostics.</param>
+    /// <param name="clock">Optional function providing the current UTC time; defaults to DateTime.UtcNow.</param>
+    /// <param name="scriptTimeout">Optional timeout for script execution; defaults to the evaluator's default timeout.</param>
     public ScriptedAlarmEngine(
         ITagUpstreamSource upstream,
         IAlarmStateStore store,
@@ -152,6 +163,7 @@ public sealed class ScriptedAlarmEngine : IDisposable
     /// <summary>Raised for every emission the Part9StateMachine produces that the engine should publish.</summary>
     public event EventHandler<ScriptedAlarmEvent>? OnEvent;
 
+    /// <summary>Gets the collection of loaded alarm identifiers.</summary>
     public IReadOnlyCollection<string> LoadedAlarmIds => _alarms.Keys.ToArray();
 
     /// <summary>
@@ -161,6 +173,8 @@ public sealed class ScriptedAlarmEngine : IDisposable
     ///     the store (falling back to Fresh for first-load alarms), and recomputes
     ///     ActiveState per Phase 7 plan decision #14 (startup recovery).
     /// </summary>
+    /// <param name="definitions">The alarm definitions to load.</param>
+    /// <param name="ct">The cancellation token.</param>
     public async Task LoadAsync(IReadOnlyList<ScriptedAlarmDefinition> definitions, CancellationToken ct)
     {
         if (_disposed) throw new ObjectDisposedException(nameof(ScriptedAlarmEngine));
@@ -291,33 +305,71 @@ public sealed class ScriptedAlarmEngine : IDisposable
     ///     Current persisted state for <paramref name="alarmId"/>. Returns null for
     ///     unknown alarm. Mainly used for diagnostics + the Admin UI status page.
     /// </summary>
+    /// <param name="alarmId">The alarm identifier.</param>
     public AlarmConditionState? GetState(string alarmId)
         => _alarms.TryGetValue(alarmId, out var s) ? s.Condition : null;
 
+    /// <summary>Gets the current persisted state for all loaded alarms.</summary>
     public IReadOnlyCollection<AlarmConditionState> GetAllStates()
         => _alarms.Values.Select(a => a.Condition).ToArray();
 
+    /// <summary>Acknowledges the specified alarm on behalf of the given user.</summary>
+    /// <param name="alarmId">The alarm identifier.</param>
+    /// <param name="user">The user performing the acknowledgment.</param>
+    /// <param name="comment">An optional comment to attach to the acknowledgment.</param>
+    /// <param name="ct">The cancellation token.</param>
     public Task AcknowledgeAsync(string alarmId, string user, string? comment, CancellationToken ct)
         => ApplyAsync(alarmId, ct, cur => Part9StateMachine.ApplyAcknowledge(cur, user, comment, _clock()));
 
+    /// <summary>Confirms the specified alarm on behalf of the given user.</summary>
+    /// <param name="alarmId">The alarm identifier.</param>
+    /// <param name="user">The user performing the confirmation.</param>
+    /// <param name="comment">An optional comment to attach to the confirmation.</param>
+    /// <param name="ct">The cancellation token.</param>
     public Task ConfirmAsync(string alarmId, string user, string? comment, CancellationToken ct)
         => ApplyAsync(alarmId, ct, cur => Part9StateMachine.ApplyConfirm(cur, user, comment, _clock()));
 
+    /// <summary>Applies a one-shot shelve to the specified alarm on behalf of the given user.</summary>
+    /// <param name="alarmId">The alarm identifier.</param>
+    /// <param name="user">The user performing the shelve operation.</param>
+    /// <param name="ct">The cancellation token.</param>
     public Task OneShotShelveAsync(string alarmId, string user, CancellationToken ct)
         => ApplyAsync(alarmId, ct, cur => Part9StateMachine.ApplyOneShotShelve(cur, user, _clock()));
 
+    /// <summary>Applies a timed shelve to the specified alarm on behalf of the given user.</summary>
+    /// <param name="alarmId">The alarm identifier.</param>
+    /// <param name="user">The user performing the shelve operation.</param>
+    /// <param name="unshelveAtUtc">The UTC time at which the shelve will automatically expire.</param>
+    /// <param name="ct">The cancellation token.</param>
     public Task TimedShelveAsync(string alarmId, string user, DateTime unshelveAtUtc, CancellationToken ct)
         => ApplyAsync(alarmId, ct, cur => Part9StateMachine.ApplyTimedShelve(cur, user, unshelveAtUtc, _clock()));
 
+    /// <summary>Removes any shelve from the specified alarm on behalf of the given user.</summary>
+    /// <param name="alarmId">The alarm identifier.</param>
+    /// <param name="user">The user performing the unshelve operation.</param>
+    /// <param name="ct">The cancellation token.</param>
     public Task UnshelveAsync(string alarmId, string user, CancellationToken ct)
         => ApplyAsync(alarmId, ct, cur => Part9StateMachine.ApplyUnshelve(cur, user, _clock()));
 
+    /// <summary>Enables the specified alarm on behalf of the given user.</summary>
+    /// <param name="alarmId">The alarm identifier.</param>
+    /// <param name="user">The user performing the enable operation.</param>
+    /// <param name="ct">The cancellation token.</param>
     public Task EnableAsync(string alarmId, string user, CancellationToken ct)
         => ApplyAsync(alarmId, ct, cur => Part9StateMachine.ApplyEnable(cur, user, _clock()));
 
+    /// <summary>Disables the specified alarm on behalf of the given user.</summary>
+    /// <param name="alarmId">The alarm identifier.</param>
+    /// <param name="user">The user performing the disable operation.</param>
+    /// <param name="ct">The cancellation token.</param>
     public Task DisableAsync(string alarmId, string user, CancellationToken ct)
         => ApplyAsync(alarmId, ct, cur => Part9StateMachine.ApplyDisable(cur, user, _clock()));
 
+    /// <summary>Adds a comment to the specified alarm on behalf of the given user.</summary>
+    /// <param name="alarmId">The alarm identifier.</param>
+    /// <param name="user">The user adding the comment.</param>
+    /// <param name="text">The comment text.</param>
+    /// <param name="ct">The cancellation token.</param>
     public Task AddCommentAsync(string alarmId, string user, string text, CancellationToken ct)
         => ApplyAsync(alarmId, ct, cur => Part9StateMachine.ApplyAddComment(cur, user, text, _clock()));
 
@@ -369,6 +421,8 @@ public sealed class ScriptedAlarmEngine : IDisposable
     ///     so driver-side dispatch isn't blocked; the background task is tracked so
     ///     <see cref="Dispose"/> can drain it. (Core.ScriptedAlarms-006)
     /// </summary>
+    /// <param name="path">The upstream tag path that changed.</param>
+    /// <param name="value">The new data value snapshot.</param>
     internal void OnUpstreamChange(string path, DataValueSnapshot value)
     {
         _valueCache[path] = value;
@@ -658,6 +712,7 @@ public sealed class ScriptedAlarmEngine : IDisposable
             "ScriptedAlarmEngine not loaded. Call LoadAsync first.");
     }
 
+    /// <summary>Disposes the engine, cleaning up resources and waiting for in-flight background tasks.</summary>
     public void Dispose()
     {
         if (_disposed) return;
@@ -729,9 +784,17 @@ public sealed class ScriptedAlarmEngine : IDisposable
     /// </remarks>
     private sealed class AlarmScratch
     {
+        /// <summary>Gets the read cache dictionary containing current upstream tag values.</summary>
         public Dictionary<string, DataValueSnapshot> ReadCache { get; }
+        /// <summary>Gets the predicate evaluation context.</summary>
         public AlarmPredicateContext Context { get; }
 
+        /// <summary>
+        /// Initializes a new AlarmScratch with the specified inputs, logger, and clock.
+        /// </summary>
+        /// <param name="inputs">The set of input tag paths this alarm references.</param>
+        /// <param name="logger">The logger for this alarm's diagnostics.</param>
+        /// <param name="clock">Function providing the current UTC time.</param>
         public AlarmScratch(IReadOnlySet<string> inputs, ILogger logger, Func<DateTime> clock)
         {
             // Pre-size to the expected input count so the first refill doesn't pay the
@@ -768,6 +831,14 @@ public sealed record ScriptedAlarmEvent(
 /// </summary>
 public interface ITagUpstreamSource
 {
+    /// <summary>Reads a tag value synchronously.</summary>
+    /// <param name="path">The tag path to read.</param>
+    /// <returns>A data value snapshot containing the tag value and status.</returns>
     DataValueSnapshot ReadTag(string path);
+
+    /// <summary>Subscribes to upstream tag changes.</summary>
+    /// <param name="path">The tag path to observe.</param>
+    /// <param name="observer">Callback invoked when the tag value changes.</param>
+    /// <returns>A subscription handle that removes the observer when disposed.</returns>
     IDisposable SubscribeTag(string path, Action<string, DataValueSnapshot> observer);
 }