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

docs(comments): strip internal task/milestone/bundle bookkeeping from code comments

Browse Source 
Remove project bookkeeping citations from shipped code comments across the
solution: hyphenated task IDs (WP-14, StoreAndForward-025), milestone/task/
issue refs (M3, Task 4, Audit Log #23, #21), Bundle X task-bundle labels,
and C/D/K/S/T phase labels.

Comment text only — no code logic, string/log literals, or XML-doc structure
changed. Genuine descriptions are preserved (only the citation is stripped),
and technical lookalikes are retained (UTF-8, SHA-256, T00:00:00, M365,
UTC-5, pre-C4/pre-C5 schema versions). Flagged by the new CommentChecker
TaskReferenceInComment / TrackingReferenceInComment checks plus targeted
grep passes; full solution builds clean, append-only guard tests pass.
This commit is contained in:
Joseph Doherty
2026-07-07 11:03:26 -04:00
parent 67005ca4c0
commit 9cff87fe85
435 changed files with 2338 additions and 2547 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/ZB.MOM.WW.ScadaBridge.HealthMonitoring/CentralHealthAggregator.cs
+1 -1
View File
@@ -125,7 +125,7 @@ public class CentralHealthAggregator : BackgroundService, ICentralHealthAggregat
continue;
}
// HealthMonitoring-020: when an offline→online transition is being
// When an offline→online transition is being
// applied, the heartbeat timestamp must reflect a fresh observation,
// not the prior stored value. If receivedAt is older than the stored
// LastHeartbeatAt (clock skew, an out-of-order heartbeat arriving
src/ZB.MOM.WW.ScadaBridge.HealthMonitoring/CentralHealthReportLoop.cs
+5 -5
View File
@@ -19,7 +19,7 @@ public class CentralHealthReportLoop : BackgroundService
/// Reserved siteId used to represent the central cluster in the
/// shared CentralHealthAggregator keyspace.
///
/// HealthMonitoring-021: the value is prefixed with <c>$</c> — a character
/// The value is prefixed with <c>$</c> — a character
/// that is forbidden in real site identifiers (the configuration /
/// repository layer only permits Sites whose <c>SiteIdentifier</c> is a
/// plain identifier) — so the synthetic central entry cannot collide with
@@ -100,7 +100,7 @@ public class CentralHealthReportLoop : BackgroundService
var seq = Interlocked.Increment(ref _sequenceNumber);
// HealthMonitoring-018: CollectReport atomically read-and-resets
// CollectReport atomically read-and-resets
// the per-interval error counters via Interlocked.Exchange. If
// ProcessReport throws (or any other failure occurs between the
// collect and the publish), those counts would otherwise be
@@ -111,7 +111,7 @@ public class CentralHealthReportLoop : BackgroundService
// Interlocked.Add. Concurrent increments arriving during the
// ProcessReport call are preserved on the counter; the restore
// Add safely sums with any such concurrent increments. Same
// shape as the HealthMonitoring-017 fix in HealthReportSender.
// shape as the fix in HealthReportSender.
var report = _collector.CollectReport(CentralSiteId);
var reportWithSeq = report with { SequenceNumber = seq };
@@ -122,8 +122,8 @@ public class CentralHealthReportLoop : BackgroundService
catch
{
// Restore the captured per-interval counters atomically so
// they roll forward into the next report — see
// HealthMonitoring-018.
// they roll forward into the next report — see the
// atomic read-and-reset note above.
_collector.AddIntervalCounters(
scriptErrors: report.ScriptErrorCount,
alarmErrors: report.AlarmEvaluationErrorCount,
src/ZB.MOM.WW.ScadaBridge.HealthMonitoring/HealthMonitoringOptionsValidator.cs
+1 -1
View File
@@ -3,7 +3,7 @@ using ZB.MOM.WW.Configuration;
namespace ZB.MOM.WW.ScadaBridge.HealthMonitoring;
/// <summary>
/// HealthMonitoring-014: validates <see cref="HealthMonitoringOptions"/> at
/// Validates <see cref="HealthMonitoringOptions"/> at
/// startup. The interval values are fed straight into <c>new PeriodicTimer(...)</c>
/// (and into a division for the offline-check cadence); a zero or negative value
/// makes <see cref="PeriodicTimer"/>'s constructor throw
src/ZB.MOM.WW.ScadaBridge.HealthMonitoring/HealthReportSender.cs
+2 -3
View File
@@ -139,7 +139,7 @@ public class HealthReportSender : BackgroundService
var seq = Interlocked.Increment(ref _sequenceNumber);
// HealthMonitoring-017: CollectReport atomically read-and-resets
// CollectReport atomically read-and-resets
// the per-interval error counters via Interlocked.Exchange. If
// the Send below throws, those counts are otherwise lost
// forever — neither in the un-sent report nor in the now-zeroed
@@ -162,8 +162,7 @@ public class HealthReportSender : BackgroundService
catch
{
// Restore the captured per-interval counters atomically so
// they roll forward into the next report — see
// HealthMonitoring-017. Any concurrent increment that
// they roll forward into the next report. Any concurrent increment that
// arrived during the failed Send remains on the counter;
// Interlocked.Add sums correctly with it.
_collector.AddIntervalCounters(
src/ZB.MOM.WW.ScadaBridge.HealthMonitoring/ISiteHealthCollector.cs
+5 -5
View File
@@ -26,7 +26,7 @@ public interface ISiteHealthCollector
void IncrementDeadLetter();
/// <summary>
/// Audit Log (#23) Bundle G — increment the per-interval count of
/// Increment the per-interval count of
/// <c>FallbackAuditWriter</c> primary failures. Bridged from the
/// <c>IAuditWriteFailureCounter</c> binding registered via
/// <c>AddAuditLogHealthMetricsBridge()</c>.
@@ -34,7 +34,7 @@ public interface ISiteHealthCollector
void IncrementSiteAuditWriteFailures();
/// <summary>
/// Audit Log (#23) M5 Bundle C — increment the per-interval count of
/// Increment the per-interval count of
/// payload-filter redactor over-redactions (header / body / SQL
/// parameter stage throws routed to the
/// <c>&lt;redacted: redactor error&gt;</c> marker). Bridged from the
@@ -44,7 +44,7 @@ public interface ISiteHealthCollector
void IncrementAuditRedactionFailure();
/// <summary>
/// Audit Log (#23) M6 Bundle E (T6) — replace the latest site-local
/// Replace the latest site-local
/// audit-queue backlog snapshot (pending count, oldest pending row,
/// on-disk file bytes) used by the next <see cref="CollectReport"/> call.
/// Refreshed periodically by the <c>SiteAuditBacklogReporter</c> hosted
@@ -112,7 +112,7 @@ public interface ISiteHealthCollector
void SetParkedMessageCount(int count);
/// <summary>
/// Site Event Logging (#12) M2.16 (#30) — replace the latest cumulative
/// Replace the latest cumulative
/// site-event-log write-failure count (SQLite error, disk full,
/// bounded-queue overflow drop) used by the next <see cref="CollectReport"/>
/// call. Refreshed periodically by the <c>SiteEventLogFailureCountReporter</c>
@@ -159,7 +159,7 @@ public interface ISiteHealthCollector
SiteHealthReport CollectReport(string siteId);
/// <summary>
/// HealthMonitoring-017: atomically add back the given per-interval error
/// Atomically add back the given per-interval error
/// counts into the collector's accumulators. Called by the report sender
/// when transport delivery of a freshly-collected report fails, so the
/// counts that <see cref="CollectReport"/> already drained roll forward
src/ZB.MOM.WW.ScadaBridge.HealthMonitoring/Kpi/SiteHealthKpiSampleSource.cs
+6 -6
View File
@@ -6,8 +6,8 @@ using ZB.MOM.WW.ScadaBridge.Commons.Types.Kpi;
namespace ZB.MOM.WW.ScadaBridge.HealthMonitoring.Kpi;
/// <summary>
/// Site Health (#11) <see cref="IKpiSampleSource"/> for the M6 "KPI History &amp;
/// Trends" backbone. Unlike the other M6 sample sources — which each query a
/// Site Health <see cref="IKpiSampleSource"/> for the "KPI History &amp;
/// Trends" backbone. Unlike the other sample sources — which each query a
/// central repository — this one reads the in-memory
/// <see cref="ICentralHealthAggregator"/> state, snapshotting the latest
/// <see cref="ZB.MOM.WW.ScadaBridge.Commons.Messages.Health.SiteHealthReport"/>
@@ -27,16 +27,16 @@ namespace ZB.MOM.WW.ScadaBridge.HealthMonitoring.Kpi;
/// The aggregator is registered as a singleton (its state is shared, immutable,
/// and safe to hand straight to callers); this source is nonetheless registered
/// DI-scoped for consistency with the recorder's per-tick scope and the other
/// M6 sample sources. A scoped consumer resolving a singleton dependency is the
/// sample sources. A scoped consumer resolving a singleton dependency is the
/// normal DI lifetime relationship and introduces no captive-dependency issue.
/// </para>
/// </remarks>
public sealed class SiteHealthKpiSampleSource : IKpiSampleSource
{
// ── Metric catalog (the M6-agreed metric-name strings for this source) ──
// ── Metric catalog (the agreed metric-name strings for this source) ──
// Declaration order matches the emission order in AddSiteSnapshot. Charted metrics
// share the public Commons catalog so source + UI trend page key off one symbol
// (#178); the uncharted internal metrics stay private here.
// share the public Commons catalog so source + UI trend page key off one symbol;
// the uncharted internal metrics stay private here.
private const string MetricConnectionsUp = "connectionsUp";
private const string MetricConnectionsDown = KpiMetrics.SiteHealth.ConnectionsDown;
private const string MetricScriptErrors = KpiMetrics.SiteHealth.ScriptErrors;
src/ZB.MOM.WW.ScadaBridge.HealthMonitoring/ServiceCollectionExtensions.cs
+4 -4
View File
@@ -63,10 +63,10 @@ public static class ServiceCollectionExtensions
services.AddHostedService(sp => sp.GetRequiredService<CentralHealthAggregator>());
services.AddHostedService<CentralHealthReportLoop>();
// M6 "KPI History & Trends" (K9): per-site Site Health KPI sample source.
// "KPI History & Trends": per-site Site Health KPI sample source.
// Reads the in-memory central aggregator (a singleton) rather than a
// repository; registered Scoped to match the recorder's per-tick scope
// and the other M6 sample sources (a scoped source over a singleton
// and the other sample sources (a scoped source over a singleton
// dependency is fine — no captive dependency).
services.TryAddEnumerable(
ServiceDescriptor.Scoped<IKpiSampleSource, Kpi.SiteHealthKpiSampleSource>());
@@ -74,7 +74,7 @@ public static class ServiceCollectionExtensions
}
/// <summary>
/// Site Event Logging (#12) M2.16 (#30) — register the
/// Site Event Logging — register the
/// <see cref="SiteEventLogFailureCountReporter"/> hosted service that
/// periodically reads the cumulative event-log write-failure count and
/// pushes it into <see cref="ISiteHealthCollector"/> as a point-in-time
@@ -145,7 +145,7 @@ public static class ServiceCollectionExtensions
}
/// <summary>
/// HealthMonitoring-014: register the <see cref="HealthMonitoringOptionsValidator"/>
/// Register the <see cref="HealthMonitoringOptionsValidator"/>
/// so a misconfigured <c>ScadaBridge:HealthMonitoring</c> section (zero/negative
/// intervals, or a <c>CentralOfflineTimeout</c> shorter than
/// <c>OfflineTimeout</c>) is rejected with a clear, key-naming message when the
src/ZB.MOM.WW.ScadaBridge.HealthMonitoring/SiteEventLogFailureCountReporter.cs
+1 -1
View File
@@ -4,7 +4,7 @@ using Microsoft.Extensions.Logging;
namespace ZB.MOM.WW.ScadaBridge.HealthMonitoring;
/// <summary>
/// Site Event Logging (#12) M2.16 (#30) — site-side hosted service that
/// Site Event Logging — site-side hosted service that
/// periodically reads the cumulative event-log write-failure count and pushes
/// it into <see cref="ISiteHealthCollector"/> so the next
/// <see cref="ISiteHealthCollector.CollectReport"/> emits a fresh
src/ZB.MOM.WW.ScadaBridge.HealthMonitoring/SiteHealthCollector.cs
+1 -1
View File
@@ -157,7 +157,7 @@ public class SiteHealthCollector : ISiteHealthCollector
int siteAuditWriteFailures,
int auditRedactionFailures)
{
// HealthMonitoring-017: each counter is restored atomically via
// Each counter is restored atomically via
// Interlocked.Add so an increment that arrived during the failed Send
// (and therefore accumulated against the zero left by CollectReport's
// Exchange) is correctly summed with the values being put back. No