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
@@ -140,7 +140,7 @@ VALUES
public async Task<IReadOnlyList<Notification>> GetDueAsync(
DateTimeOffset now, int batchSize, CancellationToken cancellationToken = default)
{
// AsNoTracking (WP2.2): the dispatcher mutates each row's delivery state in
// AsNoTracking: the dispatcher mutates each row's delivery state in
// memory and persists it through UpdateAsync, which is now a targeted
// server-side ExecuteUpdate and needs no change tracker. Tracking a batch
// of notifications — each carrying an nvarchar(max) Body and TypeData —
@@ -162,8 +162,8 @@ VALUES
{
ArgumentNullException.ThrowIfNull(n);
// Targeted server-side UPDATE of the seven mutable delivery-state columns
// (WP2.2). The predecessor called DbSet.Update(n) + SaveChanges, which
// Targeted server-side UPDATE of the seven mutable delivery-state columns.
// The predecessor called DbSet.Update(n) + SaveChanges, which
// marks EVERY property modified and rewrites all 21 columns — including
// the immutable nvarchar(max) Body/TypeData payloads — on every single
// delivery attempt. ExecuteUpdate also bypasses the change tracker
@@ -212,7 +212,7 @@ VALUES
// Same seven mutable delivery-state columns as UpdateAsync, but the WHERE
// clause below ALSO requires the row's current Status to still be Parked
// -- a single-statement compare-and-swap (arch-review 2026-08-19 P5-4).
// -- a single-statement compare-and-swap.
// Two round trips (GetByIdAsync then this write) with a status check in
// between is not a correctness guard by itself: a detached PipeTo task
// can race the dispatcher's own write (or a second concurrent operator
@@ -265,7 +265,7 @@ VALUES
public async Task<(IReadOnlyList<Notification> Rows, int TotalCount)> QueryAsync(
NotificationOutboxFilter filter, int pageNumber, int pageSize, CancellationToken cancellationToken = default)
{
// AsNoTracking (WP2.2): this is the Central UI's read-only list page. The
// AsNoTracking: this is the Central UI's read-only list page. The
// rows are projected to the wire and never saved, so tracking them cost a
// snapshot copy of every nvarchar(max) Body in the page for nothing.
var query = _context.Notifications.AsNoTracking().AsQueryable();
@@ -347,7 +347,7 @@ VALUES
{
// Time-sliced batches: each DELETE covers at most one hour of terminal rows,
// capping the lock/log footprint per statement — mirrors
// KpiHistoryRepository.PurgeOlderThanAsync (arch-review WP1.4; an unbounded
// KpiHistoryRepository.PurgeOlderThanAsync (an unbounded
// single-statement ExecuteDeleteAsync would otherwise turn a long-idle catch-up
// of the default 365-day window into one giant transaction against
// dbo.Notifications). Pure EF LINQ (no raw SQL) so this stays portable across
@@ -381,14 +381,14 @@ VALUES
// each metric is a COUNT(CASE WHEN <predicate> THEN 1 END) over the same scan
// (arch-review 04). GroupBy(_ => 1) yields a single group (no rows → no group).
//
// WP2.2 — the aggregation is now PREDICATE-RESTRICTED instead of scanning the
// The aggregation is PREDICATE-RESTRICTED instead of scanning the
// whole table. Every KPI here is about the live queue (Pending/Retrying), the
// parked backlog, or the last delivery interval; the overwhelming bulk of the
// Notifications table is historical Delivered and Discarded rows that
// contribute to NONE of them. The pre-filter below is the union of the
// metric-contributing predicates, which lets the optimizer seek the status
// index for the live/parked legs and the filtered
// (DeliveredAt) WHERE Status='Delivered' index (WP1.4) for the interval leg,
// (DeliveredAt) WHERE Status='Delivered' index for the interval leg,
// instead of paying a full scan whose cost grows with retained history.
// Mirrors the pre-filter ComputePerSiteKpisAsync/ComputePerNodeKpisAsync
// already use — the global snapshot was the odd one out.