dohertj2/lmxopcua
1
0
Fork 0
Code Issues 32 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: fill missing XML docs and strip tracking IDs from src comments

Browse Source 
Clears CommentChecker findings in src/ (3,280 -> 209, the remainder being false
positives like PLC-5/IEEE-754/M0.0) by adding missing summaries/params/returns,
normalising inheritdoc usage, and removing Gitea/review tracking IDs while keeping
the rationale they annotated. Comment-only: comment-stripped sources are identical
to the parent commit.
This commit is contained in:
Joseph Doherty
2026-10-15 06:14:58 -04:00
parent ebcbd81fca
commit 826312befe
430 changed files with 4434 additions and 3923 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Drivers/NativeAlarmProjector.cs
+17 -17
View File
@@ -41,21 +41,21 @@ public sealed class NativeAlarmProjector
/// and history are decided separately: a transition always projects a snapshot, but only a transition that
/// actually CHANGED what the condition shows (or that a source reports as genuinely new) writes a row.
/// <list type="bullet">
/// <item>Gitea #647 review — a <see cref="AlarmTransitionKind.Raise"/> on a condition already projected
/// <item>A <see cref="AlarmTransitionKind.Raise"/> on a condition already projected
/// Active WITH THE SAME MESSAGE (re-review R1 — a different message is a different alarm, and un-acks) is a
/// re-statement: what a driver whose told-record died with its instance sends after a deploy respawns
/// it. The acknowledgement is KEPT and no row is written. Only <see cref="AlarmTransitionKind.Retrigger"/>
/// (or inactive → active) un-acknowledges.</item>
/// <item>Gitea #656 — <see cref="AlarmTransitionKind.ActiveAcknowledged"/> projects Active+acked in ONE
/// <item><see cref="AlarmTransitionKind.ActiveAcknowledged"/> projects Active+acked in ONE
/// update (never an Active+unacked intermediate a client could see) and writes "Activated" only when the
/// condition was not already showing that alarm active, then "Acknowledged" only when it was not acked.</item>
/// <item>Gitea #657 — <see cref="AlarmTransitionKind.InactiveUnacknowledged"/> projects inactive+unacked in ONE
/// <item><see cref="AlarmTransitionKind.InactiveUnacknowledged"/> projects inactive+unacked in ONE
/// update and writes "Activated" + "Cleared" only when the condition was acknowledged (an un-ack needs a new
/// occurrence), "Cleared" alone when it was Active+unacked, nothing when it already showed exactly that.</item>
/// <item>Gitea #656 — a <see cref="AlarmEventArgs.IsRestatement"/> event (a source re-stating upstream's
/// <item>A <see cref="AlarmEventArgs.IsRestatement"/> event (a source re-stating upstream's
/// current state: a reconnect snapshot, first sight after a respawn) writes no row when it changes nothing
/// the condition shows: a Retrigger on an Active+unacked condition with the same message AND severity,
/// a Clear on an already-inactive condition, or an Acknowledge on an already-acknowledged one (#657); and a flagged Unspecified update of an already-active
/// a Clear on an already-inactive condition, or an Acknowledge on an already-acknowledged one; and a flagged Unspecified update of an already-active
/// condition moves its message/severity (node + one condition event) with active/acked kept and no row
/// (AbCip ALMA's governing-limit change). Unflagged sources (FOCAS, MTConnect, live Galaxy transitions) are
/// unaffected — a live Retrigger is a genuine re-occurrence and keeps its row.</item>
@@ -73,9 +73,9 @@ public sealed class NativeAlarmProjector
{
var prev = _prior.TryGetValue(nodeId, out var p)
? p : (Active: false, Acked: true, Message: (string?)null, Severity: (ushort)0);
// #626: a source with a finer scale than the four buckets supplies the exact Part 9 severity.
// A source with a finer scale than the four buckets supplies the exact Part 9 severity.
var sev = e.OpcUaSeverity is { } exact ? (ushort)Math.Clamp(exact, 1, 1000) : MapSeverity(e.Severity);
// Gitea #647 re-review R1: only a statement saying the SAME thing the condition already shows is a re-statement.
// Only a statement saying the SAME thing the condition already shows is a re-statement.
// A respawned driver cannot tell "the alarm I was showing" from "a different one that appeared while I was
// down", so a different message is treated as a new statement — un-acked, with its alerts row. Comparing the
// message is conservative: any difference (a sources' messages are deterministic for an unchanged statement)
@@ -88,7 +88,7 @@ public sealed class NativeAlarmProjector
case AlarmTransitionKind.Raise when sameMessage:
(active, acked, historyKinds) = (true, prev.Acked, []);
break;
// #656: a source re-stating an Active+unacked condition that already shows exactly this (message AND
// A source re-stating an Active+unacked condition that already shows exactly this (message AND
// severity — an MTConnect Warning→Fault escalation can keep the text) changes nothing the node shows.
case AlarmTransitionKind.Retrigger when e.IsRestatement && sameMessage && !prev.Acked && prev.Severity == sev:
(active, acked, historyKinds) = (true, false, []);
@@ -102,7 +102,7 @@ public sealed class NativeAlarmProjector
? [AlarmTransitionKind.Raise, AlarmTransitionKind.Acknowledge]
: !prev.Acked ? [AlarmTransitionKind.Acknowledge] : [];
break;
// #657: the mirror of ActiveAcknowledged — inactive AND unacked in ONE update (never Raise-then-Clear, which
// The mirror of ActiveAcknowledged — inactive AND unacked in ONE update (never Raise-then-Clear, which
// showed clients the condition Active again for an instant). Rows only for what changed: an acknowledged
// condition can only have become unacked through a new occurrence ("Activated" + "Cleared"); an
// Active+unacked one just cleared; one already inactive+unacked changed nothing.
@@ -112,7 +112,7 @@ public sealed class NativeAlarmProjector
? [AlarmTransitionKind.Raise, AlarmTransitionKind.Clear]
: prev.Active ? [AlarmTransitionKind.Clear] : [];
break;
// #657: a source re-stating an acknowledgement the condition already shows (OpcUaClient's first sight of
// A source re-stating an acknowledgement the condition already shows (OpcUaClient's first sight of
// an inactive+acked condition is a flagged Clear + Acknowledge) changes nothing.
case AlarmTransitionKind.Acknowledge when e.IsRestatement && prev.Acked:
(active, acked, historyKinds) = (prev.Active, true, []);
@@ -120,7 +120,7 @@ public sealed class NativeAlarmProjector
case AlarmTransitionKind.Acknowledge:
(active, acked, historyKinds) = (prev.Active, true, [AlarmTransitionKind.Acknowledge]);
break;
// #656: a re-stated Clear of a condition that is already inactive changes nothing (Galaxy replays every
// A re-stated Clear of a condition that is already inactive changes nothing (Galaxy replays every
// Inactive snapshot entry on each reconnect).
case AlarmTransitionKind.Clear when e.IsRestatement && !prev.Active:
(active, acked, historyKinds) = (false, prev.Acked, []);
@@ -130,7 +130,7 @@ public sealed class NativeAlarmProjector
break;
// A message/severity-only update of an ALREADY-ACTIVE condition that the source flags as a re-statement
// (AbCip ALMA: the governing limit changed but no new occurrence started, e.g. HH dropped back to H).
// OpcUaClient no longer reaches it (#657: its first sight of an inactive condition is a flagged Clear +
// OpcUaClient no longer reaches it (its first sight of an inactive condition is a flagged Clear +
// Acknowledge, or an InactiveUnacknowledged — never a flagged Unspecified).
// The node's text/severity move; active/acked are kept; NO row (an "Activated" row would be false).
case AlarmTransitionKind.Unspecified when e.IsRestatement && prev.Active:
@@ -147,14 +147,14 @@ public sealed class NativeAlarmProjector
return new AlarmConditionSnapshot(
Active: active, Acknowledged: acked, Confirmed: true, Enabled: true,
Shelving: AlarmShelvingKind.Unshelved, Severity: sev, Message: e.Message,
// #626: a per-condition source quality (MTConnect Unavailable) when the driver reports one. Absent
// (every pre-#626 source) ⇒ Good, as before — driver-wide comms loss stays the host's
// out-of-band WriteAlarmQuality annotation (#477), not something the projector infers.
// A per-condition source quality (MTConnect Unavailable) when the driver reports one. Absent
// (every earlier source) ⇒ Good, as before — driver-wide comms loss stays the host's
// out-of-band WriteAlarmQuality annotation, not something the projector infers.
StatusCode: e.QualityStatusCode ?? OpcUaStatus.Good);
}
/// <summary>
/// Gitea #641 review — record a client acknowledgement the node manager applied to <paramref name="nodeId"/>
/// Record a client acknowledgement the node manager applied to <paramref name="nodeId"/>
/// and routed toward the driver. The projector otherwise never sees it, and a later Clear would project the
/// stale unacknowledged prior. An untracked condition already defaults to acknowledged.
/// </summary>
@@ -168,7 +168,7 @@ public sealed class NativeAlarmProjector
public void Clear() => _prior.Clear();
/// <summary>
/// Gitea #641 — drop the tracked state of every condition NOT in <paramref name="deployedNodeIds"/>, keeping
/// Drop the tracked state of every condition NOT in <paramref name="deployedNodeIds"/>, keeping
/// the rest. Called on every apply instead of <see cref="Clear"/>: a condition that is still deployed keeps
/// its state across the deploy (the node manager carries the node's state across a rebuild too), so the
/// next Acknowledge does not project <c>Active = false</c> onto an active alarm and the next Clear does not