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

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
@@ -2,7 +2,7 @@ namespace ZB.MOM.WW.OtOpcUa.OpcUaServer;
/// <summary>How <see cref="AddressSpaceApplier"/> must mutate the address space for a given
/// <see cref="AddressSpacePlan"/>. A pure policy classification OVER the planner's diff (the planner stays
/// a pure diff; the kind is the applier's routing policy over that diff — see R2-07 03/P1).</summary>
/// a pure diff; the kind is the applier's routing policy over that diff).</summary>
public enum AddressSpaceChangeKind
{
/// <summary><see cref="AddressSpacePlan.IsEmpty"/> — nothing to do.</summary>
@@ -58,7 +58,7 @@ public static class AddressSpaceChangeClassifier
// RawTagDeltaIsSurgicalEligible, and a changed vtag UNLESS it is node-irrelevant. Evaluated BEFORE the
// add/remove split so a non-surgical change alongside pure adds still rebuilds.
//
// WP4 BINDING GUARD (Wave C review M3), as narrowed by the 2026-08-15 surgical-deploys work. The
// BINDING GUARD, as narrowed by the 2026-08-15 surgical-deploys work. The
// guard's subject is NATIVE-ALARM NOTIFIER WIRING: a native alarm's set of referencing equipment lives
// in RawTagPlan.ReferencingEquipmentPaths (part of its record equality), and only a rebuild clears +
// re-wires those notifiers, so an ALARM-BEARING raw tag (Alarm != null on EITHER side) still routes to
@@ -130,6 +130,9 @@ public static class AddressSpaceChangeClassifier
// so a delta changing ONLY those three leaves a byte-identical node and needs no address-space rebuild.
// Whitelist-of-may-differ via `with` + the record's custom Equals: any OTHER field difference (current
// or future) makes the override unequal → falls back to a full rebuild (safe default).
/// <summary>Whether a changed equipment virtual tag differs only in fields that do not affect its materialised node.</summary>
/// <param name="d">The virtual-tag delta to classify.</param>
/// <returns><see langword="true"/> when only Expression / DependencyRefs / Historize differ; otherwise <see langword="false"/>.</returns>
internal static bool VtagDeltaIsNodeIrrelevant(AddressSpacePlan.EquipmentVirtualTagDelta d) =>
(d.Previous with
{
@@ -153,6 +156,9 @@ public static class AddressSpaceChangeClassifier
// TagConfigIntent.Parse falls back to the RAW TagConfig blob as FullName, so a DataType/
// array edit also mutates that blob ⇒ FullName differs ⇒ this returns false ⇒ full rebuild. That is the
// correct safe default (a protocol driver's subscription needs re-spawning for a new shape anyway).
/// <summary>Whether a changed equipment tag can be updated in place on its existing node instead of rebuilding.</summary>
/// <param name="d">The equipment-tag delta to classify.</param>
/// <returns><see langword="true"/> when the tag has no alarm and differs only in the in-place-updatable attributes; otherwise <see langword="false"/>.</returns>
internal static bool TagDeltaIsSurgicalEligible(AddressSpacePlan.EquipmentTagDelta d) =>
d.Previous.Alarm is null && d.Current.Alarm is null &&
(d.Previous with
@@ -167,12 +173,15 @@ public static class AddressSpaceChangeClassifier
// v3 surgical raw-tag eligibility: a NON-alarm raw tag whose only differences are the in-place-updatable
// attributes (Writable / IsHistorized / HistorianTagname / DataType / IsArray / ArrayLength / ArrayWritable)
// and/or its ReferencingEquipmentPaths. ArrayWritable (Gitea #610) only feeds the node's writability — the
// and/or its ReferencingEquipmentPaths. ArrayWritable only feeds the node's writability — the
// same AccessLevel + OnWriteValue swap Writable already drives in place — so it must be listed here or
// every array-tag edit that flips it would fall through to a full rebuild. The referencing set is node-inert for a VALUE tag — it only drives native-alarm
// notifier wiring (the WP4 guard), which is why Alarm != null on EITHER side disqualifies. Identity fields
// notifier wiring (the binding guard), which is why Alarm != null on EITHER side disqualifies. Identity fields
// (NodeId is the diff key; TagId / DriverInstanceId / Name / ParentNodeId / Realm) still force a rebuild via
// the with-equality default-closed pattern.
/// <summary>Whether a changed raw tag can be updated in place on its existing node instead of rebuilding.</summary>
/// <param name="d">The raw-tag delta to classify.</param>
/// <returns><see langword="true"/> when the tag has no alarm and differs only in the in-place-updatable attributes or its referencing equipment paths; otherwise <see langword="false"/>.</returns>
internal static bool RawTagDeltaIsSurgicalEligible(AddressSpacePlan.RawTagDelta d) =>
d.Previous.Alarm is null && d.Current.Alarm is null &&
(d.Previous with