docs(client): document Galaxy fallback operator-comment limitation + pin null behavior

Closes backlog #12: Galaxy's AckMsg attribute is WRITE-ONLY and the OPC UA
event SelectClause carries no comment field, making OperatorComment
unrecoverable on the sub-attribute fallback path. Documents the two concrete
reasons in-code and tightens the AlarmEventArgs XML doc; adds pinning test
OnAlarmEvent_GalaxyFallback_LeavesOperatorCommentNull.
This commit is contained in:
Joseph Doherty
2026-06-18 13:06:37 -04:00
parent 6c6a2c4203
commit fac4418708
3 changed files with 92 additions and 3 deletions
@@ -81,9 +81,13 @@ public sealed class AlarmEventArgs : EventArgs
/// <summary>
/// PR E.7 — Operator-supplied comment recorded by the upstream alarm system on
/// Acknowledge transitions. Null on raise / clear, or when the upstream path
/// can't surface the comment (sub-attribute fallback path collapses comments
/// into a single string write).
/// Acknowledge transitions. Null on raise / clear events, and intentionally null
/// on the Galaxy OPC UA sub-attribute fallback path for two unrecoverable reasons:
/// (a) Galaxy's <c>AckMsg</c> attribute is WRITE-ONLY — no readable attribute
/// exposes the last operator comment — and (b) the OPC UA event SelectClause
/// carries no comment field. The operator comment is only available via the
/// gateway's native alarm feed (<c>GalaxyAlarmTransition.OperatorComment</c>
/// in the Galaxy driver path).
/// </summary>
public string? OperatorComment { get; }