dohertj2/ScadaBridge
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

docs(src): fix CommentChecker findings across src/ — 1,032 → 5 (all false positives)

Browse Source 
Comment/XML-doc changes only, no code logic:
- strip project-tracking references (WP*, P*-*, row-NN, #NN, Task N) from
  comments, keeping the explanatory rationale
- add missing summaries, <param>, <returns>, <typeparam> and <inheritdoc/>
- replace misused <inheritdoc/> with real docs; where <inheritdoc/> was
  combined with useful remarks, move the rationale into // comments
- drop stale replicationActor <param> on DeploymentManagerActor ctor

Remaining 5 are false positives (CWE-1236 x2, failures-1, year-0001, M365).
Build 0 errors / 0 warnings.
This commit is contained in:
Joseph Doherty
2026-10-07 14:12:25 -04:00
parent 3a217b9484
commit 0ffd4bdbea
217 changed files with 1224 additions and 695 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/ZB.MOM.WW.ScadaBridge.HealthMonitoring/ISiteHealthCollector.cs
+5 -7
View File
@@ -26,7 +26,7 @@ public interface ISiteHealthCollector
void IncrementDeadLetter();
/// <summary>
/// WP3.1: increments the per-interval count of script/alarm runs SHED because
/// Increments the per-interval count of script/alarm runs SHED because
/// <c>MaxConcurrentRunsPerScript</c> runs were already in flight for that script. A raw
/// per-interval count like the script/alarm error counters — a sustained non-zero value
/// means a trigger is firing faster than its script can complete. Every shed is counted
@@ -199,7 +199,7 @@ public interface ISiteHealthCollector
}
/// <summary>
/// Replace the latest per-node deployed-secrets mirror statuses (review finding M1) used
/// Replace the latest per-node deployed-secrets mirror statuses used
/// by the <c>SecretMirrorStatuses</c> field of the next <see cref="CollectReport"/> call.
/// Refreshed periodically by the site-side <c>SecretMirrorStatusReporter</c> from the
/// LocalDb-replicated <c>secret_mirror_status</c> table, so the ACTIVE node's report
@@ -225,7 +225,7 @@ public interface ISiteHealthCollector
/// <param name="busyThreads">Worker threads currently executing a script.</param>
/// <param name="oldestBusyAgeSeconds">Age (seconds) of the oldest in-flight script, or <c>null</c> when idle.</param>
/// <param name="detachedThreads">
/// WP3.1: worker threads the stuck-script watchdog has detached and replaced because
/// Worker threads the stuck-script watchdog has detached and replaced because
/// their script wedged past its deadline plus grace, and which have not yet returned.
/// A non-zero, non-draining value means script bodies are permanently blocking threads.
/// </param>
@@ -236,8 +236,7 @@ public interface ISiteHealthCollector
}
/// <summary>
/// WP2.6d (arch-review misc — site stream alarm-vs-attribute shared buffer):
/// replace the latest cumulative count of alarm state changes dropped from
/// Replaces the latest cumulative count of alarm state changes dropped from
/// <c>SiteStreamManager</c>'s dedicated alarm publish queue, used by the next
/// <see cref="CollectReport"/> call. Refreshed periodically by the site-side
/// <c>SiteStreamAlarmDropReporter</c> hosted service. Point-in-time: NOT reset on
@@ -300,8 +299,7 @@ public interface ISiteHealthCollector
/// <param name="siteAuditWriteFailures">Site audit write failure count to add back.</param>
/// <param name="auditRedactionFailures">Audit redaction failure count to add back.</param>
/// <param name="scriptRunShedCount">
/// Interval-drained script/alarm run-shed count to add back (arch-review 2026-08-19
/// P8-1). Additive trailing parameter defaulting to 0 so existing callers keep
/// Interval-drained script/alarm run-shed count to add back. Additive trailing parameter defaulting to 0 so existing callers keep
/// compiling; <c>DetachedScriptThreads</c>/<c>SiteStreamAlarmDropCount</c> are
/// point-in-time gauges, not drained on collect, so they need no restore path.
/// </param>
src/ZB.MOM.WW.ScadaBridge.HealthMonitoring/LocalDbReplicationStatusReporter.cs
+1 -1
View File
@@ -159,6 +159,6 @@ public sealed class LocalDbReplicationStatusReporter : IHostedService, IDisposab
}
}
/// <inheritdoc />
/// <summary>Releases the cancellation source used by the polling loop.</summary>
public void Dispose() => _cts?.Dispose();
}
src/ZB.MOM.WW.ScadaBridge.HealthMonitoring/ServiceCollectionExtensions.cs
+1 -1
View File
@@ -171,7 +171,7 @@ public static class ServiceCollectionExtensions
/// <see cref="AddSiteEventLogHealthMetricsBridge"/>. Pass the backlog through as
/// nullable — coercing null to 0 would report an unreadable oplog as a healthy one.
/// <para>
/// <paramref name="replicationConfiguredProvider"/> is the register-row-80 gate: the
/// <paramref name="replicationConfiguredProvider"/> is the replication-configured gate: the
/// replication engine is registered unconditionally and answers <c>false</c>/<c>0</c>
/// while inert, so without it a deliberately-unreplicated site publishes
/// "disconnected, empty backlog" instead of the documented "no reading" null. The
src/ZB.MOM.WW.ScadaBridge.HealthMonitoring/SiteHealthCollector.cs
+7 -8
View File
@@ -32,7 +32,7 @@ public class SiteHealthCollector : ISiteHealthCollector
// -1 = reconciler SKIPPED (no IDeploymentConfigFetcher)
// Null must stay distinct from -1: "we don't know" is not "self-heal is missing".
private volatile int _startupReconcilerActive;
// Review finding M1: every site node's deployed-secrets mirror status, refreshed by the
// Every site node's deployed-secrets mirror status, refreshed by the
// SiteRuntime SecretMirrorStatusReporter. Null = the reporter has not run (or its read
// failed before it ever succeeded) — "no data", distinct from an empty list.
private volatile IReadOnlyList<SecretMirrorNodeStatus>? _secretMirrorStatuses;
@@ -53,13 +53,13 @@ public class SiteHealthCollector : ISiteHealthCollector
private int _scriptQueueDepth;
private int _scriptBusyThreads;
private long _scriptOldestBusyAgeBits = BitConverter.DoubleToInt64Bits(double.NaN);
// WP3.1: workers detached and replaced by the stuck-script watchdog and not yet exited
// Workers detached and replaced by the stuck-script watchdog and not yet exited
// (point-in-time, from the same reporter tick as the gauges above), and the per-interval
// count of runs shed by the per-script in-flight cap (reset on collect like the error
// counters, and restored by AddIntervalCounters when a report fails to send).
private int _scriptDetachedThreads;
private int _scriptRunShedCount;
// WP2.6d: cumulative alarm-publish-queue drop count, refreshed by
// Cumulative alarm-publish-queue drop count, refreshed by
// SiteStreamAlarmDropReporter. Point-in-time (not reset on collect), like the
// scheduler gauges above.
private long _siteStreamAlarmDropCount;
@@ -263,8 +263,7 @@ public class SiteHealthCollector : ISiteHealthCollector
// (and therefore accumulated against the zero left by CollectReport's
// Exchange) is correctly summed with the values being put back. No
// ordering between the six Adds is required — they target independent
// fields. scriptRunShedCount joins this restore path (arch-review
// 2026-08-19 P8-1) because it is drained by CollectReport the same way
// fields. scriptRunShedCount joins this restore path because it is drained by CollectReport the same way
// as the other five; DetachedScriptThreads and SiteStreamAlarmDropCount
// are point-in-time gauges (CompareExchange/Read, never zeroed on
// collect) so a failed Send loses nothing for them to restore.
@@ -330,10 +329,10 @@ public class SiteHealthCollector : ISiteHealthCollector
ScriptQueueDepth = Interlocked.CompareExchange(ref _scriptQueueDepth, 0, 0),
ScriptBusyThreads = Interlocked.CompareExchange(ref _scriptBusyThreads, 0, 0),
ScriptOldestBusyAgeSeconds = ReadScriptOldestBusyAgeSeconds(),
// WP3.1: point-in-time (like the three gauges above), so a CompareExchange read
// Point-in-time (like the three gauges above), so a CompareExchange read
// rather than an Exchange reset.
DetachedScriptThreads = Interlocked.CompareExchange(ref _scriptDetachedThreads, 0, 0),
// WP3.1: per-interval, so drained on collect like the error counters.
// Per-interval, so drained on collect like the error counters.
ScriptRunShedCount = Interlocked.Exchange(ref _scriptRunShedCount, 0),
// Both fields come from the ONE snapshot read above. Null (the reporter has
// not run) leaves both report fields null — "no data", not "disconnected
@@ -344,7 +343,7 @@ public class SiteHealthCollector : ISiteHealthCollector
// Tri-state: 0 stays null ("not reported"), which must never collapse into
// false ("self-heal is missing"). Register row 73.
StartupReconcilerActive = startupReconciler == 0 ? null : startupReconciler > 0,
// M1: point-in-time, not drained; null stays null ("no data").
// Point-in-time, not drained; null stays null ("no data").
SecretMirrorStatuses = _secretMirrorStatuses
};
}
src/ZB.MOM.WW.ScadaBridge.HealthMonitoring/SiteHealthState.cs
+1 -1
View File
@@ -44,7 +44,7 @@ public sealed record SiteHealthState
/// Gets the instant this site was first observed by the aggregator (via a
/// report or a heartbeat); <c>null</c> only for states not built by the
/// aggregator (hand-constructed fixtures). Anchors metrics-staleness for a
/// site that has NEVER delivered a report (review 01 round-2 N3): with
/// site that has NEVER delivered a report: with
/// <see cref="LastReportReceivedAt"/> null the staleness check previously
/// skipped the site forever. <see cref="LastHeartbeatAt"/> cannot anchor
/// this — every heartbeat advances it.