docs(xmldoc): fill missing XML docs + strip tracking-ID comments across src
v2-ci / build (push) Failing after 41s
v2-ci / unit-tests (tests/Core/ZB.MOM.WW.OtOpcUa.Cluster.Tests) (push) Has been skipped
v2-ci / unit-tests (tests/Server/ZB.MOM.WW.OtOpcUa.ControlPlane.Tests) (push) Has been skipped
v2-ci / unit-tests (tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests) (push) Has been skipped
v2-ci / unit-tests (tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests) (push) Has been skipped
v2-ci / unit-tests (tests/Server/ZB.MOM.WW.OtOpcUa.Security.Tests) (push) Has been skipped
v2-ci / integration (tests/Server/ZB.MOM.WW.OtOpcUa.Host.IntegrationTests) (push) Has been skipped
v2-ci / integration (tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests) (push) Has been skipped

Adds <summary>/<param>/<returns>/<inheritdoc> where missing and removes
project bookkeeping IDs (task/tracking refs) from shipped code comments,
so the docs read cleanly and CommentChecker is quiet except for known
false positives (PLC/protocol terms, event/IEqualityComparer inheritdoc).
Doc/comment-only; no logic changed; solution builds clean.
This commit is contained in:
Joseph Doherty
2026-07-07 12:38:39 -04:00
parent 384dbd7d36
commit 9cad9ed0fc
375 changed files with 1899 additions and 2493 deletions
@@ -27,6 +27,7 @@ public static class DirectLogicAddress
/// V-address that may fall in either bank, call <see cref="VMemoryToPdu"/>, which routes
/// system-bank addresses through <see cref="SystemVMemoryToPdu"/> instead.
/// </remarks>
/// <returns>The 0-based Modbus PDU address for the given user V-memory address.</returns>
/// <exception cref="ArgumentException">Input is null / empty / contains non-octal digits (8,9).</exception>
/// <exception cref="OverflowException">Parsed value exceeds ushort.MaxValue (0xFFFF).</exception>
public static ushort UserVMemoryToPdu(string vAddress)
@@ -80,11 +81,16 @@ public static class DirectLogicAddress
/// <remarks>Octal 40400 == decimal 16640 (0x4100).</remarks>
public const ushort SystemVMemoryOctalBase = 0x4100; // octal 40400 decoded
/// <summary>
/// Convert a 0-based offset within the system V-memory bank to its absolute Modbus PDU
/// address, relocated to the fixed <see cref="SystemVMemoryBasePdu"/> base.
/// </summary>
/// <param name="offsetWithinSystemBank">
/// 0-based register offset within the system bank. Pass 0 for V40400 itself; pass 1 for
/// V40401 (octal), and so on. NOT an octal-decoded value — the system bank lives at
/// consecutive PDU addresses, so the offset is plain decimal.
/// </param>
/// <returns>The 0-based Modbus PDU address for the given system-bank offset.</returns>
public static ushort SystemVMemoryToPdu(ushort offsetWithinSystemBank)
{
var pdu = SystemVMemoryBasePdu + offsetWithinSystemBank;
@@ -107,6 +113,7 @@ public static class DirectLogicAddress
/// octal-decoded value itself: V40400 → PDU 0x2100, V40401 → 0x2101, and so on.
/// See <c>docs/v2/dl205.md</c> §V-Memory Addressing.
/// </remarks>
/// <returns>The 0-based Modbus PDU address for the given V-memory address.</returns>
/// <exception cref="ArgumentException">Input is null / empty / contains non-octal digits.</exception>
/// <exception cref="OverflowException">The result exceeds the 16-bit Modbus PDU range.</exception>
public static ushort VMemoryToPdu(string vAddress)
@@ -116,11 +123,11 @@ public static class DirectLogicAddress
return (ushort)octalValue;
// System bank: the registers are contiguous from V40400, so the offset within the bank
// is the plain decimal distance from the octal base, not another octal decode.
// Driver.Modbus.Addressing-011: the subtraction result is provably <= 0xBEFF because
// DecodeOctalVAddress already caps octalValue at 0xFFFF, so no overflow guard is needed
// here. The real overflow guard (pdu > ushort.MaxValue) lives in SystemVMemoryToPdu and
// is reachable only when that helper is called directly with a large explicit offset.
// is the plain decimal distance from the octal base, not another octal decode. The
// subtraction result is provably <= 0xBEFF because DecodeOctalVAddress already caps
// octalValue at 0xFFFF, so no overflow guard is needed here. The real overflow guard
// (pdu > ushort.MaxValue) lives in SystemVMemoryToPdu and is reachable only when that
// helper is called directly with a large explicit offset.
var offsetWithinBank = (ushort)(octalValue - SystemVMemoryOctalBase);
return SystemVMemoryToPdu(offsetWithinBank);
}
@@ -156,6 +163,7 @@ public static class DirectLogicAddress
/// ladder-logic editor's notation.
/// </summary>
/// <param name="yAddress">The Y-output address (octal, with optional Y prefix).</param>
/// <returns>The 0-based Modbus coil address.</returns>
public static ushort YOutputToCoil(string yAddress) =>
AddOctalOffset(YOutputBaseCoil, StripPrefix(yAddress, 'Y'));
@@ -164,6 +172,7 @@ public static class DirectLogicAddress
/// 0-based Modbus coil address.
/// </summary>
/// <param name="cAddress">The C-relay address (octal, with optional C prefix).</param>
/// <returns>The 0-based Modbus coil address.</returns>
public static ushort CRelayToCoil(string cAddress) =>
AddOctalOffset(CRelayBaseCoil, StripPrefix(cAddress, 'C'));
@@ -173,6 +182,7 @@ public static class DirectLogicAddress
/// exception — the CPU sizes the table to configured I/O, not installed modules.
/// </summary>
/// <param name="xAddress">The X-input address (octal, with optional X prefix).</param>
/// <returns>The 0-based Modbus discrete-input address.</returns>
public static ushort XInputToDiscrete(string xAddress) =>
AddOctalOffset(XInputBaseDiscrete, StripPrefix(xAddress, 'X'));
@@ -181,6 +191,7 @@ public static class DirectLogicAddress
/// Modbus discrete-input address. Accepts <c>"SP"</c> prefix case-insensitively.
/// </summary>
/// <param name="spAddress">The SP special-relay address (octal, with optional SP prefix).</param>
/// <returns>The 0-based Modbus discrete-input address.</returns>
public static ushort SpecialToDiscrete(string spAddress)
{
if (string.IsNullOrWhiteSpace(spAddress))