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:
@@ -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"),
|
||||
|
||||
Reference in New Issue
Block a user