docs: backfill XML documentation across 756 files
v2-ci / build (push) Failing after 1m43s
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>, <typeparam>, and <inheritdoc/> tags to public
members surfaced by commentchecker — resolves 5,847 of 5,869 issues
(99.6%) across three /fixdocs passes.
This commit is contained in:
Joseph Doherty
2026-05-28 08:10:17 -04:00
parent f9fc7dd2e1
commit 64e3fbe035
756 changed files with 9876 additions and 96 deletions
@@ -21,6 +21,7 @@ public static class DirectLogicAddress
/// depends on CPU model — DL205 D2-260 user memory is V1400-V7377 + V10000-V17777
/// octal, DL260 extends to V77777 octal.
/// </summary>
/// <param name="vAddress">The V-memory address (octal, with optional V prefix).</param>
/// <remarks>
/// This handles ONLY user V-memory (octal address below the system base, V40400). For a
/// V-address that may fall in either bank, call <see cref="VMemoryToPdu"/>, which routes
@@ -100,6 +101,7 @@ public static class DirectLogicAddress
/// V-memory (octal &gt;= V40400) is relocated to the fixed system base at PDU 0x2100.
/// This is the address the parser must use — the system bank is NOT a simple octal decode.
/// </summary>
/// <param name="vAddress">The V-memory address (octal, with optional V prefix).</param>
/// <remarks>
/// The system-bank consecutive offset is the octal-decoded distance from V40400, not an
/// octal-decoded value itself: V40400 → PDU 0x2100, V40401 → 0x2101, and so on.
@@ -152,6 +154,7 @@ public static class DirectLogicAddress
/// 0-based Modbus coil address on DL260. The trailing number is OCTAL, matching the
/// ladder-logic editor's notation.
/// </summary>
/// <param name="yAddress">The Y-output address (octal, with optional Y prefix).</param>
public static ushort YOutputToCoil(string yAddress) =>
AddOctalOffset(YOutputBaseCoil, StripPrefix(yAddress, 'Y'));
@@ -159,6 +162,7 @@ public static class DirectLogicAddress
/// Translate a DirectLOGIC C-relay address (e.g. <c>"C0"</c>, <c>"C1777"</c>) to its
/// 0-based Modbus coil address.
/// </summary>
/// <param name="cAddress">The C-relay address (octal, with optional C prefix).</param>
public static ushort CRelayToCoil(string cAddress) =>
AddOctalOffset(CRelayBaseCoil, StripPrefix(cAddress, 'C'));
@@ -167,6 +171,7 @@ public static class DirectLogicAddress
/// 0-based Modbus discrete-input address. Reading an unpopulated X returns 0, not an
/// 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>
public static ushort XInputToDiscrete(string xAddress) =>
AddOctalOffset(XInputBaseDiscrete, StripPrefix(xAddress, 'X'));
@@ -174,6 +179,7 @@ public static class DirectLogicAddress
/// Translate a DirectLOGIC SP-special-relay address (e.g. <c>"SP0"</c>) to its 0-based
/// 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>
public static ushort SpecialToDiscrete(string spAddress)
{
if (string.IsNullOrWhiteSpace(spAddress))
@@ -60,6 +60,9 @@ public static class MelsecAddress
/// Translate a MELSEC Y-output address to a 0-based Modbus coil address. Same rules
/// as <see cref="XInputToDiscrete"/> for hex/octal parsing.
/// </summary>
/// <param name="yAddress">MELSEC Y address. <c>Y</c> prefix optional, case-insensitive.</param>
/// <param name="family">The PLC family — determines whether the trailing digits are hex or octal.</param>
/// <param name="yBankBase">0-based Modbus coil address the assignment-block has configured Y0 to land at.</param>
public static ushort YOutputToCoil(string yAddress, MelsecFamily family, ushort yBankBase = 0) =>
AddFamilyOffset(yBankBase, StripPrefix(yAddress, 'Y'), family);
@@ -68,6 +71,8 @@ public static class MelsecAddress
/// address. M-addresses are <b>decimal</b> on every MELSEC family — unlike X/Y which
/// are hex on Q/L/iQ-R. Includes the bank base that the assignment-block configured.
/// </summary>
/// <param name="mAddress">MELSEC M address. <c>M</c> prefix optional, case-insensitive.</param>
/// <param name="mBankBase">0-based Modbus coil address the assignment-block has configured M0 to land at.</param>
public static ushort MRelayToCoil(string mAddress, ushort mBankBase = 0)
{
var digits = StripPrefix(mAddress, 'M');
@@ -86,6 +91,8 @@ public static class MelsecAddress
/// D0 → HR 0 (pass <paramref name="dBankBase"/> = 0); sites with shifted layouts pass
/// their configured base.
/// </summary>
/// <param name="dAddress">MELSEC D address. <c>D</c> prefix optional, case-insensitive.</param>
/// <param name="dBankBase">0-based Modbus holding register address the assignment-block has configured D0 to land at.</param>
public static ushort DRegisterToHolding(string dAddress, ushort dBankBase = 0)
{
var digits = StripPrefix(dAddress, 'D');
@@ -42,9 +42,15 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus;
public static class ModbusAddressParser
{
/// <summary>Parse an address string. Throws <see cref="FormatException"/> on invalid input.</summary>
/// <param name="address">The address string to parse.</param>
/// <returns>The parsed Modbus address.</returns>
public static ParsedModbusAddress Parse(string address) => Parse(address, ModbusFamily.Generic, MelsecFamily.Q_L_iQR);
/// <summary>Parse with a family hint (#144 family-native branch).</summary>
/// <param name="address">The address string to parse.</param>
/// <param name="family">The Modbus family hint.</param>
/// <param name="melsecSubFamily">The MELSEC subfamily hint.</param>
/// <returns>The parsed Modbus address.</returns>
public static ParsedModbusAddress Parse(string address, ModbusFamily family, MelsecFamily melsecSubFamily = MelsecFamily.Q_L_iQR)
{
if (TryParse(address, family, melsecSubFamily, out var parsed, out var error))
@@ -52,6 +58,13 @@ public static class ModbusAddressParser
throw new FormatException(error);
}
/// <summary>
/// Attempts to parse an address string with default family hints.
/// </summary>
/// <param name="address">The address string to parse.</param>
/// <param name="result">The parsed address, or null if parsing fails.</param>
/// <param name="error">The error message if parsing fails, or null on success.</param>
/// <returns>True if parsing succeeded; otherwise false.</returns>
public static bool TryParse(string? address, out ParsedModbusAddress? result, out string? error)
=> TryParse(address, ModbusFamily.Generic, MelsecFamily.Q_L_iQR, out result, out error);
@@ -61,6 +74,12 @@ public static class ModbusAddressParser
/// and falls back to Modicon / mnemonic on miss. <paramref name="result"/> is null and
/// <paramref name="error"/> non-null on failure.
/// </summary>
/// <param name="address">The address string to parse.</param>
/// <param name="family">The Modbus family hint.</param>
/// <param name="melsecSubFamily">The MELSEC subfamily hint.</param>
/// <param name="result">The parsed address, or null if parsing fails.</param>
/// <param name="error">The error message if parsing fails, or null on success.</param>
/// <returns>True if parsing succeeded; otherwise false.</returns>
public static bool TryParse(string? address, ModbusFamily family, MelsecFamily melsecSubFamily,
out ParsedModbusAddress? result, out string? error)
{
@@ -41,6 +41,10 @@ public static class ModbusModiconAddress
/// surface a structured diagnostic rather than throw. <paramref name="error"/> is
/// <c>null</c> on success.
/// </summary>
/// <param name="address">The address string to parse (5-digit or 6-digit form).</param>
/// <param name="region">The parsed Modbus region, or default if parsing fails.</param>
/// <param name="offset">The zero-based PDU offset, or 0 if parsing fails.</param>
/// <param name="error">The error message if parsing fails, or null on success.</param>
public static bool TryParse(string? address, out ModbusRegion region, out ushort offset, out string? error)
{
region = default;