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
@@ -24,6 +24,7 @@ public static class TwinCATDriverFactoryExtensions
/// <summary>Creates a TwinCAT driver instance from the provided configuration.</summary>
/// <param name="driverInstanceId">The driver instance identifier.</param>
/// <param name="driverConfigJson">The driver configuration as JSON.</param>
/// <returns>The constructed <see cref="TwinCATDriver"/> instance.</returns>
internal static TwinCATDriver CreateInstance(string driverInstanceId, string driverConfigJson)
{
ArgumentException.ThrowIfNullOrWhiteSpace(driverInstanceId);
@@ -35,10 +36,11 @@ public static class TwinCATDriverFactoryExtensions
/// Parse a TwinCAT driver-config JSON document into a <see cref="TwinCATDriverOptions"/>.
/// Shared by <see cref="CreateInstance"/> (constructor-time) and
/// <see cref="TwinCATDriver.InitializeAsync"/> / <see cref="TwinCATDriver.ReinitializeAsync"/>
/// so a config generation pushed via Reinitialize is actually applied (Driver.TwinCAT-001).
/// so a config generation pushed via Reinitialize is actually applied.
/// </summary>
/// <param name="driverConfigJson">The JSON configuration string.</param>
/// <param name="driverInstanceId">The driver instance identifier.</param>
/// <returns>The parsed <see cref="TwinCATDriverOptions"/>.</returns>
internal static TwinCATDriverOptions ParseOptions(string driverConfigJson, string driverInstanceId)
{
ArgumentException.ThrowIfNullOrWhiteSpace(driverConfigJson);
@@ -79,6 +81,7 @@ public static class TwinCATDriverFactoryExtensions
/// </summary>
/// <param name="driverConfigJson">The JSON configuration string.</param>
/// <param name="driverInstanceId">The driver instance identifier.</param>
/// <returns>The parsed <see cref="TwinCATDriverOptions"/>.</returns>
public static TwinCATDriverOptions ParseOptionsForTests(string driverConfigJson, string driverInstanceId)
=> ParseOptions(driverConfigJson, driverInstanceId);
@@ -86,13 +89,6 @@ public static class TwinCATDriverFactoryExtensions
{
var dataType = ParseEnum<TwinCATDataType>(t.DataType, t.Name, driverInstanceId, "DataType");
// Driver.TwinCAT-003: Structure-typed pre-declared tags are not supported. The driver's
// atomic surface cannot read/write UDT blobs — MapToClrType falls through to typeof(int)
// and ConvertForWrite throws NotSupportedException, producing garbage reads or late
// runtime failures. BrowseSymbolsAsync expands a Structure/UDT/FB symbol into its atomic
// member leaves (the container itself is never surfaced as a writable Structure node), so the
// supported way to address members is discovery — not a pre-declared Structure tag. Reject here
// with a clear error so operators get a configuration-time failure, not a silent wrong value.
if (dataType == TwinCATDataType.Structure)
throw new InvalidOperationException(
$"TwinCAT tag '{t.Name ?? "<unnamed>"}' in '{driverInstanceId}' specifies " +
@@ -110,9 +106,6 @@ public static class TwinCATDriverFactoryExtensions
DataType: dataType,
Writable: t.Writable ?? true,
WriteIdempotent: t.WriteIdempotent ?? false,
// Driver.TwinCAT-017: thread arrayLength through so JSON-authored pre-declared tags can
// declare 1-D arrays (Phase 4c). Only positive values are honoured; null / non-positive
// keeps the scalar default (ArrayLength: null on TwinCATTagDefinition).
ArrayLength: t.ArrayLength is > 0 ? t.ArrayLength : null);
}
@@ -192,7 +185,7 @@ public static class TwinCATDriverFactoryExtensions
/// <summary>
/// Optional 1-D array element count. When positive, the tag is a 1-D array of this
/// many <see cref="DataType"/> elements — drives <c>IsArray</c>/<c>ArrayDim</c> at
/// discovery and a native ADS array read at runtime (Phase 4c, Driver.TwinCAT-017).
/// discovery and a native ADS array read at runtime (Phase 4c).
/// <c>null</c> or non-positive = scalar (the default).
/// </summary>
public int? ArrayLength { get; init; }