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
@@ -29,7 +29,7 @@ public sealed class AdminOperationsActor : ReceiveActor
private readonly TagConfigValidationMode _tagConfigValidationMode;
/// <summary>
/// Where central→node commands are handed off (per-cluster mesh Phase 2), or
/// Where central→node commands are handed off (per-cluster mesh), or
/// <see langword="null"/> to publish on the mediator directly.
/// </summary>
private readonly IActorRef? _meshRouter;
@@ -43,7 +43,7 @@ public sealed class AdminOperationsActor : ReceiveActor
/// <param name="tagConfigValidationMode">Deploy-gate TagConfig strictness mode (Warn default | Error opt-in).</param>
/// <param name="meshRouter">
/// Central comm actor commands are handed to, or <see langword="null"/> to publish on the
/// DistributedPubSub mediator directly (the pre-Phase-2 behaviour).
/// DistributedPubSub mediator directly (the behaviour before the per-cluster mesh).
/// </param>
/// <returns>Props configured to create an AdminOperationsActor.</returns>
public static Props Props(
@@ -87,8 +87,8 @@ public sealed class AdminOperationsActor : ReceiveActor
/// no router is wired.
/// </summary>
/// <remarks>
/// The fallback keeps ~12 existing tests (and any node wired before per-cluster mesh Phase 2)
/// on exactly the pre-Phase-2 behaviour. The DistributedPubSub branch behind it is
/// The fallback keeps ~12 existing tests (and any node wired before per-cluster mesh)
/// on exactly the pre-mesh behaviour. The DistributedPubSub branch behind it is
/// <b>retained</b>, not scheduled for deletion — an earlier note here promised Phase 6 would
/// remove it, which was deliberately reversed (<c>docs/Configuration.md</c> § "The compiled
/// transport-mode defaults were deliberately NOT flipped"): DPS is still the correct and
@@ -245,12 +245,12 @@ public sealed class AdminOperationsActor : ReceiveActor
errors.AddRange(DraftValidator.ValidateClusterTopology(cluster, nodes));
}
// R2-11 (05/CONV-2): deploy-time TagConfig strictness inspection over equipment tags. The
// Deploy-time TagConfig strictness inspection over equipment tags. The
// driver-typed EquipmentTagConfigInspector surfaces every blob the driver's own reader would
// REJECT — a present-but-invalid enum value, an absent or malformed address field, a
// structurally-unparseable TagConfig — each of which makes the driver skip the tag so it reads
// BadNodeIdUnknown forever. (Pre-R2-11 Phase C the runtime silently defaulted a typo'd enum;
// it has rejected the tag since, so these warnings describe rejections.) In Warn mode
// BadNodeIdUnknown forever. (The runtime used to silently default a typo'd enum;
// it now rejects the tag, so these warnings describe rejections.) In Warn mode
// (default) these are non-blocking (logged + appended to the accepted result Message); in Error
// mode they fold into the reject list so a typo'd config cannot be re-deployed until fixed.
// Running servers are untouched either way — the gate only sees re-deploys.
@@ -51,7 +51,7 @@ public static class ConfigComposer
UnsAreas = await db.UnsAreas.AsNoTracking().OrderBy(x => x.UnsAreaId).ToListAsync(ct),
UnsLines = await db.UnsLines.AsNoTracking().OrderBy(x => x.UnsLineId).ToListAsync(ct),
NodeAcls = await db.NodeAcls.AsNoTracking().OrderBy(x => x.NodeAclId).ToListAsync(ct),
// #520 stage 4: the data-plane credentials travel with the config, because a driver-only node
// the data-plane credentials travel with the config, because a driver-only node
// has no ConfigDb to read them from (per-cluster mesh Phase 4) and would otherwise deny every
// UserName token. Only the peppered HMAC of each secret ships — never the secret — and the
// pepper is node configuration that is deliberately NOT in the artifact, so a stolen blob
@@ -15,17 +15,17 @@ using ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
namespace ZB.MOM.WW.OtOpcUa.ControlPlane.AdminOperations;
/// <summary>
/// Deploy-time TagConfig inspection dispatched by <c>DriverType</c> (R2-11, 05/CONV-2). Mirrors the
/// Deploy-time TagConfig inspection dispatched by <c>DriverType</c>. Mirrors the
/// AdminUI <c>TagConfigValidator</c> shape: a case-insensitive map from the canonical driver-type string
/// to that driver's lightweight <c>Contracts</c> parser <c>Inspect()</c>, returning human-readable
/// warnings. Never throws.
/// <para><b>The warnings describe REJECTIONS, not silent defaults.</b> Every driver's runtime read has
/// been strict since R2-11 Phase C (<c>TagConfigJson.TryReadEnumStrict</c>): a present-but-invalid enum
/// been strict (<c>TagConfigJson.TryReadEnumStrict</c>): a present-but-invalid enum
/// value — like an absent or malformed address field, or an unparseable document — makes the reader
/// refuse the whole tag, so the driver skips it and it reads <c>BadNodeIdUnknown</c> forever with the
/// deployment otherwise green. That is what these warnings are for. (Before Phase C the runtime did
/// silently substitute a default for a typo'd enum; the doc-comments here and on the per-driver
/// <c>Inspect</c> methods still said so until Gitea #551.) Because a warning can be PROMOTED to a
/// <c>Inspect</c> methods used to say so.) Because a warning can be PROMOTED to a
/// blocking error by <c>TagConfigValidationMode.Error</c>, each <c>Inspect</c> asks its driver's own
/// reader for the verdict and only explains a refusal — never restating the rule, and so never able to
/// be stricter than the runtime it reports on.</para>
@@ -1,7 +1,7 @@
namespace ZB.MOM.WW.OtOpcUa.ControlPlane.AdminOperations;
/// <summary>
/// How the deploy gate treats TagConfig strictness inspection results (R2-11, 05/CONV-2). Sourced from
/// How the deploy gate treats TagConfig strictness inspection results. Sourced from
/// <c>Deployment:TagConfigValidationMode</c> in appsettings; defaults to <see cref="Warn"/> so existing
/// deployments are never blocked by a previously-tolerated typo.
/// </summary>