review(Driver.AbCip.Contracts): first review; document IsArray/Writable contract

First review at 7286d320. 6 findings (doc fixes -005/-006 resolved; -001 writable-hardcode,
-002 Dt-units doc, -003 dead [Display] attrs, -004 parser test gap left Open). Surfaced
cross-module: AbCipTagDto/AbCipMemberDto in the factory drop ElementCount/IsArray.
This commit is contained in:
Joseph Doherty
2026-06-19 12:22:53 -04:00
parent a19b0f8612
commit a4d24b5cf5
3 changed files with 234 additions and 1 deletions
@@ -142,7 +142,8 @@ public sealed record AbCipDeviceOptions(
/// had <c>isArray:true</c> (with <c>arrayLength &gt;= 1</c>); the tag discovers as an OPC UA
/// array node (<c>IsArray</c> + <c>ArrayDim</c>) and reads as a typed CLR array — even when
/// <paramref name="ElementCount"/> is 1 (a valid 1-element array). <c>ElementCount</c> alone
/// cannot carry this because a scalar and a 1-element array both have a count of 1.</param>
/// cannot carry this because a scalar and a 1-element array both have a count of 1.
/// Ignored for <see cref="AbCipDataType.Structure"/>.</param>
public sealed record AbCipTagDefinition(
string Name,
string DeviceHostAddress,
@@ -12,6 +12,12 @@ public static class AbCipEquipmentTagParser
/// <param name="reference">The equipment tag's TagConfig JSON (also used as the def identity).</param>
/// <param name="def">The transient definition when parsing succeeds.</param>
/// <returns><see langword="true"/> when <paramref name="reference"/> is an AbCip TagConfig object.</returns>
/// <remarks>
/// The produced <see cref="AbCipTagDefinition.Writable"/> is always <c>true</c>: the
/// TagConfig JSON format for equipment tags does not carry a writability field, so the
/// PLC's ExternalAccess attribute is the effective write gate. Operators who need a
/// read-only OPC UA surface must rely on the PLC's ExternalAccess rejecting the write.
/// </remarks>
public static bool TryParse(string reference, out AbCipTagDefinition def)
{
def = null!;