From 3b5ef439d49f94295694b8d7b7f78d2e1e2100a1 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Fri, 10 Jul 2026 06:23:12 -0400 Subject: [PATCH] docs(xmldoc): fix genuine doc issues surfaced by /fixdocs (17 fixes) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - CapabilityInvoker: 3 methods that implement IDriverCapabilityInvoker now use instead of duplicating the interface docs (MissingInheritDoc). - TwinCAT NativeRegistration ctor: added the 8 missing tags (MissingParam). - Stripped the arch-review bookkeeping IDs STAB-1 (IS7Plc, S7Driver) + STAB-2 (TwinCATDriver x4) from comments, keeping the descriptive text. Left the other 86 flagged items untouched — they are checker false positives on legitimate technical content: interface-implemented events / IEqualityComparer / IDisposable members whose IS correct (10 InheritDocMisused), and domain terms the heuristic misreads as tracking IDs (IEEE-754, S7-1200/300/400/1500, PLC-5, D2-260, S7/Melsec memory addresses, OPC UA Part 9, phase-N design-doc filename refs, UNS level-N descriptions, and prose like 'the #1 bug source' / failover 'pick #3'). --- .../Resilience/CapabilityInvoker.cs | 29 ++----------------- .../ZB.MOM.WW.OtOpcUa.Driver.S7/IS7Plc.cs | 2 +- .../ZB.MOM.WW.OtOpcUa.Driver.S7/S7Driver.cs | 2 +- .../TwinCATDriver.cs | 16 +++++++--- 4 files changed, 17 insertions(+), 32 deletions(-) diff --git a/src/Core/ZB.MOM.WW.OtOpcUa.Core/Resilience/CapabilityInvoker.cs b/src/Core/ZB.MOM.WW.OtOpcUa.Core/Resilience/CapabilityInvoker.cs index 6c55d4b1..8b4f5b66 100644 --- a/src/Core/ZB.MOM.WW.OtOpcUa.Core/Resilience/CapabilityInvoker.cs +++ b/src/Core/ZB.MOM.WW.OtOpcUa.Core/Resilience/CapabilityInvoker.cs @@ -57,13 +57,7 @@ public sealed class CapabilityInvoker : IDriverCapabilityInvoker _statusTracker = statusTracker; } - /// Execute a capability call returning a value, honoring the per-capability pipeline. - /// Return type of the underlying driver call. - /// The driver capability being executed. - /// The host name for logging and status tracking. - /// The async function to execute. - /// Cancellation token for the operation. - /// The result of the underlying driver call. + /// public async ValueTask ExecuteAsync( DriverCapability capability, string hostName, @@ -87,12 +81,7 @@ public sealed class CapabilityInvoker : IDriverCapabilityInvoker } } - /// Execute a void-returning capability call, honoring the per-capability pipeline. - /// The driver capability being executed. - /// The host name for logging and status tracking. - /// The async function to execute. - /// Cancellation token for the operation. - /// A task that represents the asynchronous operation. + /// public async ValueTask ExecuteAsync( DriverCapability capability, string hostName, @@ -116,19 +105,7 @@ public sealed class CapabilityInvoker : IDriverCapabilityInvoker } } - /// - /// Execute a call honoring - /// semantics — if is false, retries are disabled regardless - /// of the tag-level configuration (the pipeline for a non-idempotent write never retries). - /// If true, the call runs through the capability's pipeline which may - /// retry when the tier configuration permits. - /// - /// Return type of the underlying driver call. - /// The host name for logging and status tracking. - /// Whether the write operation is idempotent. - /// The async function to execute. - /// Cancellation token for the operation. - /// The result of the underlying driver write call. + /// public async ValueTask ExecuteWriteAsync( string hostName, bool isIdempotent, diff --git a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7/IS7Plc.cs b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7/IS7Plc.cs index 083b584b..8707a9a1 100644 --- a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7/IS7Plc.cs +++ b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7/IS7Plc.cs @@ -11,7 +11,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.S7; /// /// The seam exists so can dispose a dead handle and /// re-open a fresh one after a transient PLC reboot / network blip — the reconnect path -/// (STAB-1) — and so that path is unit-testable via a fake without a +/// — and so that path is unit-testable via a fake without a /// live PLC (S7.Net ships no in-process fake and is sealed). Mirrors /// the TwinCAT driver's ITwinCATClient / ITwinCATClientFactory pattern. /// diff --git a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7/S7Driver.cs b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7/S7Driver.cs index fca4b08d..282fecd1 100644 --- a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7/S7Driver.cs +++ b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7/S7Driver.cs @@ -1172,7 +1172,7 @@ public sealed class S7Driver /// /// Returns a live S7 connection, lazily disposing a dead handle and re-opening a fresh one - /// when the previous connection dropped (STAB-1 reconnect path). The fast path returns the + /// when the previous connection dropped (the reconnect path). The fast path returns the /// current when it is still connected and not marked dead; otherwise it /// builds + opens a new connection via with the same /// timeout-linked CTS the initial connect uses. diff --git a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriver.cs b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriver.cs index 0db36c00..4748f844 100644 --- a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriver.cs +++ b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriver.cs @@ -447,7 +447,7 @@ public sealed class TwinCATDriver : IDriver, IReadable, IWritable, ITagDiscovery // true, otherwise fall through to the shared PollGroupEngine. Native path registers one // notification per tag against the target's PLC runtime — the PLC pushes changes on its own // cycle so we skip the poll loop entirely. Each registration stores its REPLAYABLE INTENT on - // the owning device so EnsureConnectedAsync can re-register it after a reconnect (STAB-2). + // the owning device so EnsureConnectedAsync can re-register it after a reconnect. public async Task SubscribeAsync( IReadOnlyList fullReferences, TimeSpan publishingInterval, CancellationToken cancellationToken) { @@ -577,6 +577,14 @@ public sealed class TwinCATDriver : IDriver, IReadable, IWritable, ITagDiscovery private ITwinCATNotificationHandle? _handle; /// Initializes a new instance of the class. + /// Globally-unique registration id (registry key on the device). + /// The device this notification is registered against. + /// Driver-side full reference the pushed value is reported under. + /// ADS symbol name (resolved from the symbol path). + /// Declared data type. + /// Bit index for a BOOL-within-word symbol; null otherwise. + /// Requested notification interval. + /// Value-change callback (closes over the owning subscription handle + reference). public NativeRegistration(long id, DeviceState device, string reference, string symbolName, TwinCATDataType dataType, int? bitIndex, TimeSpan interval, Action onChange) { @@ -627,7 +635,7 @@ public sealed class TwinCATDriver : IDriver, IReadable, IWritable, ITagDiscovery // A locally-connected client whose wire probe FAILS is wire-dead but port-open: // force a recycle so the next tick rebuilds + replays native notifications. Without // this the IsConnected fast-path would keep handing back the dead client forever - // (the STAB-2 compounding bug — native pushes would never recover). + // (the compounding bug — native pushes would never recover). if (!success) await RecycleClientAsync(state).ConfigureAwait(false); } @@ -716,7 +724,7 @@ public sealed class TwinCATDriver : IDriver, IReadable, IWritable, ITagDiscovery /// The connect-or-reconnect core, assuming the caller already holds /// . When it installs a NEW client (a genuine /// reconnect, not a fast-path reuse) it replays every stored native-notification intent - /// onto it — otherwise native ADS pushes would silently stop after a drop (STAB-2). Both + /// onto it — otherwise native ADS pushes would silently stop after a drop. Both /// the initial subscribe () and the probe loop call /// through here under the same gate, so a replay can never race a register. /// @@ -907,7 +915,7 @@ public sealed class TwinCATDriver : IDriver, IReadable, IWritable, ITagDiscovery /// Live native-notification registrations against this device, keyed by registration id. /// Holds the replayable intent (symbol / type / bit / interval / callback), not just /// an opaque handle, so that when swaps in - /// a fresh client after a drop it can re-register every notification onto it (STAB-2). + /// a fresh client after a drop it can re-register every notification onto it. /// Populated by SubscribeAsync, drained by UnsubscribeAsync / teardown. /// public ConcurrentDictionary NativeRegistrations { get; } = new();