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

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
@@ -357,7 +357,7 @@ public sealed class EmailNotificationDeliveryAdapter : INotificationDeliveryAdap
}
// OAuth2 XOAUTH2 requires the user identity (FromAddress)
// to be sent alongside the access token; an empty user is rejected by M365.
// to be sent alongside the access token; an empty user is rejected by Microsoft 365.
await smtp.AuthenticateAsync(
config.AuthType,
credentials,
@@ -36,7 +36,7 @@ namespace ZB.MOM.WW.ScadaBridge.NotificationOutbox.Kpi;
/// omitted when the age is <c>null</c>.
/// </para>
/// <para>
/// <b>deliveredLastInterval rescale (P5-5, arch-review Low).</b>
/// <b>deliveredLastInterval rescale.</b>
/// <see cref="KpiMetricAggregationCatalog"/> classifies this metric as a
/// <see cref="KpiRollupAggregation.Rate"/>: the central hourly rollup fold sums every
/// sample recorded in the hour, which is only correct if each sample's value is a
@@ -79,7 +79,7 @@ public sealed class NotificationOutboxKpiSampleSource : IKpiSampleSource
/// <param name="options">Outbox options carrying the stuck-age and delivered-window cutoffs.</param>
/// <param name="kpiHistoryOptions">
/// KPI History options carrying <see cref="KpiHistoryOptions.SampleInterval"/> — the
/// recorder's sampling cadence the deliveredLastInterval sample is rescaled onto (P5-5),
/// recorder's sampling cadence the deliveredLastInterval sample is rescaled onto,
/// so the hourly rollup fold's per-sample sum stays correct independent of
/// <see cref="NotificationOutboxOptions.DeliveredKpiWindow"/>.
/// </param>
@@ -1111,7 +1111,7 @@ public class NotificationOutboxActor : ReceiveActor, IWithTimers
notification.NextAttemptAt = null;
notification.LastError = null;
// Compare-and-swap on Status == Parked (arch-review 2026-08-19 P5-4). The
// Compare-and-swap on Status == Parked. The
// read above and this write are two separate round trips; a detached
// PipeTo task can race the dispatcher's own write (or a second
// concurrent operator action) in between, so the in-memory check above
@@ -1203,8 +1203,7 @@ public class NotificationOutboxActor : ReceiveActor, IWithTimers
notification.Status = NotificationStatus.Discarded;
// Same compare-and-swap on Status == Parked as the retry path (arch-review
// 2026-08-19 P5-4): a purge between the read and the write leaves nothing
// Same compare-and-swap on Status == Parked as the retry path: a purge between the read and the write leaves nothing
// to discard, and a dispatcher/other-operator write landing in that same
// window (e.g. a delivery succeeding) must not be silently clobbered by a
// blind write of this stale in-memory copy. Re-read on a lost CAS to
@@ -3,9 +3,9 @@ using ZB.MOM.WW.Configuration;
namespace ZB.MOM.WW.ScadaBridge.NotificationOutbox;
/// <summary>
/// Validates <see cref="NotificationOutboxOptions"/> at host startup (arch-review
/// §1.5 eager-options-validation pattern — this options class had no registered
/// validator before P5-5). The durations feed the dispatch sweep, stuck-call
/// Validates <see cref="NotificationOutboxOptions"/> at host startup (eager
/// options validation — this options class previously had no registered
/// validator). The durations feed the dispatch sweep, stuck-call
/// detection, terminal-row purge, and the delivered-throughput KPI window; a
/// zero/negative cadence would spin an Akka scheduler, and a non-positive
/// <see cref="NotificationOutboxOptions.DeliveredKpiWindow"/> would collapse the
@@ -56,7 +56,7 @@ public static class ServiceCollectionExtensions
{
ArgumentNullException.ThrowIfNull(services);
// Eager startup validation (arch-review §1.5 / P5-5): this options class had no
// Eager startup validation (arch-review §1.5): this options class had no
// registered validator before — ValidateOnStart makes a bad
// ScadaBridge:NotificationOutbox section fail fast at boot with a clear,
// key-naming message instead of spinning a scheduler or, for DeliveredKpiWindow,