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
@@ -45,7 +45,7 @@ public interface ITelemetrySubscription : IDisposable
/// <summary>
/// Process-wide, node-local fan-out hub sitting between this node's own telemetry producers and the
/// (Phase-5) gRPC streaming service central dials into.
/// gRPC streaming service central dials into.
/// </summary>
/// <remarks>
/// <para>
@@ -68,6 +68,7 @@ public interface ITelemetryLocalHub
/// on a full channel) and, for the two snapshot-style items, updates the last-value cache that
/// primes future subscribers.
/// </summary>
/// <param name="item">The telemetry item to fan out.</param>
void Emit(TelemetryItem item);
/// <summary>
@@ -83,22 +84,25 @@ public interface ITelemetryLocalHub
/// priming before the reader ever drains them. The node-local cache holds only THIS node's
/// instances (a handful), so a normal large capacity leaves ample headroom.
/// </param>
/// <returns>The subscription whose reader yields the cached snapshots, then live deltas.</returns>
ITelemetrySubscription Subscribe(int boundedCapacity);
/// <summary>
/// Drops the cached Health and Resilience snapshots of a driver instance that has been removed from
/// this node, so a later <see cref="Subscribe"/> no longer replays its last-known state. Live
/// subscribers are not told; the instance simply stops emitting. Unknown ids are a no-op.
/// <para>The eviction also <b>holds</b> (#609): a removed instance's child stops asynchronously and can
/// <para>The eviction also <b>holds</b>: a removed instance's child stops asynchronously and can
/// still publish after this call (a health snapshot when an in-flight connect or subscribe finishes),
/// so until <see cref="Readmit"/> every later Health/Resilience item for the instance is dropped — not
/// cached and not fanned out.</para>
/// </summary>
/// <param name="driverInstanceId">The removed driver instance's id.</param>
void Evict(string driverInstanceId);
/// <summary>
/// Lifts an earlier <see cref="Evict"/> so a driver instance spawned again under the same id (a later
/// deployment re-adding it) publishes normally. A no-op for an id that was never evicted.
/// </summary>
/// <param name="driverInstanceId">The driver instance id to readmit.</param>
void Readmit(string driverInstanceId) { }
}
@@ -8,7 +8,7 @@ namespace ZB.MOM.WW.OtOpcUa.Runtime.Telemetry;
/// </summary>
/// <remarks>
/// <para>
/// <b>No DPS.</b> This hub is fed only by this node's own in-process producers (a later Phase-5
/// <b>No DPS.</b> This hub is fed only by this node's own in-process producers (a later
/// task taps them). It never subscribes to cluster DistributedPubSub — see the invariant on
/// <see cref="ITelemetryLocalHub"/>.
/// </para>
@@ -37,12 +37,12 @@ public sealed class TelemetryLocalHub : ITelemetryLocalHub
// Snapshot last-value caches. Only ever mutated under _gate (kept ConcurrentDictionary so a
// Subscribe reading them under the gate is trivially safe even against any future lock-free read).
// Entries are evicted via Evict when DriverHostActor removes the instance (#609), so a
// Entries are evicted via Evict when DriverHostActor removes the instance, so a
// decommissioned driver's last-known state does not replay to new subscribers.
private readonly ConcurrentDictionary<string, TelemetryItem.Health> _healthCache = new();
private readonly ConcurrentDictionary<(string InstanceId, string HostName), TelemetryItem.Resilience> _resilienceCache = new();
// Instances evicted and not since readmitted (#609). Their late Health/Resilience items are dropped, so a
// Instances evicted and not since readmitted. Their late Health/Resilience items are dropped, so a
// removed driver's still-stopping child cannot re-prime the cache it was just evicted from. Under _gate.
private readonly HashSet<string> _evicted = new(StringComparer.Ordinal);
@@ -141,6 +141,10 @@ public sealed class TelemetryLocalHub : ITelemetryLocalHub
private readonly Guid _id;
private int _disposed;
/// <summary>Creates a subscription over a hub channel.</summary>
/// <param name="hub">The owning hub, notified on dispose.</param>
/// <param name="id">The subscription id.</param>
/// <param name="channel">The channel whose reader is exposed.</param>
public Subscription(TelemetryLocalHub hub, Guid id, Channel<TelemetryItem> channel)
{
_hub = hub;
@@ -148,8 +152,10 @@ public sealed class TelemetryLocalHub : ITelemetryLocalHub
Reader = channel.Reader;
}
/// <inheritdoc />
public ChannelReader<TelemetryItem> Reader { get; }
/// <summary>Detaches this subscription from the hub; safe to call more than once.</summary>
public void Dispose()
{
if (Interlocked.Exchange(ref _disposed, 1) != 0)