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
@@ -47,7 +47,7 @@ public static class ModbusTagDefinitionFactory
|| !addr.TryGetInt32(out var address)
|| address < 0 || address > ushort.MaxValue)
return false;
// Strict enum reads (R2-11 Phase C): a present-but-invalid (typo'd) enum rejects the tag
// Strict enum reads: a present-but-invalid (typo'd) enum rejects the tag
// (→ BadNodeIdUnknown) instead of silently defaulting to a wrong-width Good.
if (!TagConfigJson.TryReadEnumStrict(root, "region", ModbusRegion.HoldingRegisters, out var region)) return false;
if (!TagConfigJson.TryReadEnumStrict(root, "dataType", ModbusDataType.Int16, out var dataType)) return false;
@@ -72,9 +72,9 @@ public static class ModbusTagDefinitionFactory
var arrayLength = ReadInt(root, "arrayLength");
int? arrayCount = (isArray && arrayLength >= 1) ? arrayLength : null;
// "writable" defaults to true when absent (today's value) — makes read-only equipment tags
// authorable (UNDER-6). Node-level authz remains the effective write gate.
// authorable. Node-level authz remains the effective write gate.
var writable = TagConfigJson.ReadWritable(root);
// CONV-4: optional per-tag unitId (0–255). Absent ⇒ null ⇒ the driver-level UnitId via
// Optional per-tag unitId (0–255). Absent ⇒ null ⇒ the driver-level UnitId via
// ModbusDriver.ResolveUnitId, so multi-unit equipment tags key their own per-host breaker.
var unitId = ReadOptionalByte(root, "unitId");
// Optional per-tag encoding/planner knobs — carried on the def so a RawTagEntry round-trips
@@ -137,18 +137,18 @@ public static class ModbusTagDefinitionFactory
private const string InspectionRawPath = "(inspect)";
/// <summary>
/// Deploy-time inspection of an equipment-tag <c>TagConfig</c> blob (05/CONV-2). Returns
/// Deploy-time inspection of an equipment-tag <c>TagConfig</c> blob. Returns
/// human-readable warnings for a blob <see cref="FromTagConfig"/> would <b>reject</b> — a
/// structurally unparseable or non-object document, an absent <c>region</c>, an absent or
/// out-of-range <c>address</c>, a present-but-invalid <c>region</c> / <c>dataType</c> /
/// <c>byteOrder</c> / <c>stringByteOrder</c> (each rejects the tag: the runtime enum reads are
/// STRICT since R2-11 Phase C), or a type-dependent guard (<c>String</c> with no
/// STRICT), or a type-dependent guard (<c>String</c> with no
/// <c>stringLength</c>, <c>BitInRegister</c> with a <c>bitIndex</c> outside 0–15). Such a tag is
/// skipped by the driver and reads <c>BadNodeIdUnknown</c> forever. Empty when the mapper accepts
/// the blob, when it is blank, or when it is not an equipment-tag TagConfig object. Never throws.
/// </summary>
/// <remarks>
/// <b>The verdict comes from <see cref="FromTagConfig"/>, not from a mirror</b> (Gitea #551). The
/// <b>The verdict comes from <see cref="FromTagConfig"/>, not from a mirror</b>. The
/// rule this gate must never break is being stricter than the runtime — a blob the driver serves
/// must not draw a warning calling it invalid — and running the mapper first makes that structural
/// rather than a promise. It also closes the opposite gap: the previous hand-list of enum checks
@@ -160,7 +160,7 @@ public static class ModbusTagDefinitionFactory
public static IReadOnlyList<string> Inspect(string reference)
{
var warnings = new List<string>();
// Gitea #556 item 1: the framing check TRIMS FIRST. FromTagConfig hands the blob straight to
// The framing check TRIMS FIRST. FromTagConfig hands the blob straight to
// JsonDocument.Parse, which tolerates leading whitespace — so an untrimmed check let " {…}" be
// read (and possibly REFUSED) by the driver while drawing zero deploy warnings. A reference that
// still does not start with '{' after trimming is not an equipment-tag TagConfig at all and keeps
@@ -232,7 +232,7 @@ public static class ModbusTagDefinitionFactory
}
// Strict enums, in the order FromTagConfig reads them. stringByteOrder is read as strictly as its
// three siblings, and was the one the previous hand-list forgot (Gitea #551).
// three siblings, and was the one the previous hand-list forgot.
foreach (var w in new[]
{
TagConfigJson.DescribeInvalidEnum<ModbusRegion>(root, "region"),