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:
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user