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:
Joseph Doherty
2026-10-15 06:14:58 -04:00
parent ebcbd81fca
commit 826312befe
430 changed files with 4434 additions and 3923 deletions
@@ -22,7 +22,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus;
public sealed class ModbusDriver
: IDriver, ITagDiscovery, IReadable, IWritable, IBatchSubscribable, IHostConnectivityProbe, IPerCallHostResolver, ISkippedTagReporter, IDisposable, IAsyncDisposable
{
/// <summary>Authored tags this driver could not build into its poll table (Gitea #541).</summary>
/// <summary>Authored tags this driver could not build into its poll table.</summary>
private readonly SkippedTagLedger _skippedTags = new();
/// <inheritdoc />
@@ -30,8 +30,8 @@ public sealed class ModbusDriver
// ---- instance fields (grouped at top for auditability) ----
/// <summary>Mutable so <see cref="InitializeAsync"/> can adopt a re-parsed config on reinitialize
/// (#516). Only ever written on the init path, before any reader/transport uses it.</summary>
/// <summary>Mutable so <see cref="InitializeAsync"/> can adopt a re-parsed config on reinitialize.
/// Only ever written on the init path, before any reader/transport uses it.</summary>
private ModbusDriverOptions _options;
private readonly Func<ModbusDriverOptions, IModbusTransport> _transportFactory;
private readonly string _driverInstanceId;
@@ -196,11 +196,11 @@ public sealed class ModbusDriver
new KeyValuePair<string, object?>(OtOpcUaTelemetry.PollOverrunDriverInstanceTag, driverInstanceId)));
}
/// <summary>Upper bound on the poll-loop failure backoff — adopts the S7-proven 30 s cap fleet-wide (05/STAB-8).</summary>
/// <summary>Upper bound on the poll-loop failure backoff — adopts the S7-proven 30 s cap fleet-wide.</summary>
private static readonly TimeSpan PollBackoffCap = TimeSpan.FromSeconds(30);
/// <summary>
/// 05/STAB-9 — routes a poll-loop reader failure to the driver health surface: logs it and
/// Routes a poll-loop reader failure to the driver health surface: logs it and
/// degrades to <see cref="DriverState.Degraded"/> preserving <c>LastSuccessfulRead</c>.
/// Never downgrades a <see cref="DriverState.Faulted"/> state (a stronger, config-level signal).
/// </summary>
@@ -213,16 +213,15 @@ public sealed class ModbusDriver
WriteHealth(new DriverHealth(DriverState.Degraded, current.LastSuccessfulRead, ex.Message));
}
/// <summary>
/// Resolve a reference to the per-slave host key (<c>host:port/unitN</c>) that keys its
/// per-host resilience (bulkhead / circuit breaker). CONV-4: routes through
/// <see cref="EquipmentTagRefResolver{TDef}"/> so an equipment-tag reference (raw TagConfig
/// JSON) keys its OWN authored unit — via the tag's optional <c>unitId</c> or the driver
/// default — rather than the single-slave fallback. The resolver caches parses, so this adds
/// no per-call cost after first use.
/// </summary>
/// <param name="fullReference">The tag reference (authored name or equipment-tag JSON).</param>
/// <returns>The per-slave host key.</returns>
// <summary>
// Resolve a reference to the per-slave host key (<c>host:port/unitN</c>) that keys its
// per-host resilience (bulkhead / circuit breaker). Routes through
// <see cref="EquipmentTagRefResolver{TDef}"/> so an equipment-tag reference (raw TagConfig
// JSON) keys its OWN authored unit — via the tag's optional <c>unitId</c> or the driver
// default — rather than the single-slave fallback. The resolver caches parses, so this adds
// no per-call cost after first use.
// </summary>
/// <inheritdoc />
public string ResolveHost(string fullReference)
{
if (_resolver.TryResolve(fullReference, out var tag))
@@ -319,7 +318,7 @@ public sealed class ModbusDriver
_transport = null;
}
// #516: re-parse the supplied DriverConfig so a config change delivered through the IDriver
// re-parse the supplied DriverConfig so a config change delivered through the IDriver
// contract is honoured. Without this the driver keeps serving the options it was CONSTRUCTED
// with, so an operator's edit is discarded while the deployment still seals green. An empty /
// placeholder document (the "{}" some unit tests pass) keeps the constructor-supplied options.
@@ -54,7 +54,7 @@ public static class ModbusDriverFactoryExtensions
/// <summary>
/// Parses a Modbus <c>DriverConfig</c> JSON document into typed options. Extracted from
/// <see cref="CreateInstance(string,string,ILoggerFactory?)"/> so <see cref="ModbusDriver.InitializeAsync"/>
/// can re-parse a CHANGED config on reinitialize (Gitea #516) rather than serving the options it was
/// can re-parse a CHANGED config on reinitialize rather than serving the options it was
/// constructed with — which silently discarded every edit while the deployment still sealed green.
/// </summary>
/// <param name="driverInstanceId">The unique identifier for the driver instance.</param>
@@ -31,7 +31,7 @@ public sealed class ModbusDriverProbe : IDriverProbe
/// <summary>The parsed probe target — host/port/unitId + the effective connection timeout + the wire
/// transport mode, all read from the SAME factory DTO shape (<c>ModbusDriverConfigDto</c>) the driver
/// factory parses, so <c>timeoutMs</c> binds identically to the factory (R2-11, 05/CONV-2; the
/// factory parses, so <c>timeoutMs</c> binds identically to the factory (the
/// OpcUaClient parity rule) and an <c>RtuOverTcp</c>-authored config probes over RTU framing —
/// matching how the driver will actually run.</summary>
internal readonly record struct ProbeTarget(string Host, int Port, byte UnitId, TimeSpan Timeout, ModbusTransportMode Transport);
@@ -25,7 +25,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus;
/// </para>
/// <para>
/// Every transaction runs under a per-op deadline (a linked
/// <see cref="CancellationTokenSource.CancelAfter(TimeSpan)"/>, design §7 / R2-01) so a
/// <see cref="CancellationTokenSource.CancelAfter(TimeSpan)"/>, design §7) so a
/// frozen gateway can never wedge a poll: the deadline firing is normalised to a
/// <see cref="ModbusTransportDesyncException"/> and tears the socket down so the next attempt
/// reconnects. A <b>caller</b> cancellation is distinguished from that timeout and propagates