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
@@ -18,7 +18,7 @@ public static class ServiceCollectionExtensions
{
// The buffer now lives in the consolidated LocalDb database at LocalDb:Path, not
// at StoreAndForwardOptions.SqliteDbPath — that option survives only as the
// migrator's source location (Task 8).
// migrator's source location.
services.AddSingleton<StoreAndForwardStorage>(sp => new StoreAndForwardStorage(
sp.GetRequiredService<ILocalDb>(),
sp.GetRequiredService<ILogger<StoreAndForwardStorage>>()));
@@ -8,8 +8,8 @@ public class StoreAndForwardOptions
/// <summary>
/// Path to the legacy standalone store-and-forward SQLite file. <b>Migration-only.</b>
/// The buffer itself lives in the consolidated LocalDb database (<c>LocalDb:Path</c>)
/// as of LocalDb Phase 2; this path is read once at boot by
/// <c>SiteLocalDbLegacyMigrator</c> to drain a pre-Phase-2 file, and is otherwise
/// now; this path is read once at boot by
/// <c>SiteLocalDbLegacyMigrator</c> to drain a pre-consolidation file, and is otherwise
/// unused. A node that has already migrated may leave it set or unset.
/// </summary>
public string SqliteDbPath { get; set; } = "./data/store-and-forward.db";
@@ -40,7 +40,7 @@ public class StoreAndForwardOptions
public int SweepTargetParallelism { get; set; } = 4;
/// <summary>
/// WP2.6c (arch-review misc — unbounded S&amp;F observer queue): capacity of the
/// Capacity of the
/// cached-call audit-observer pump's queue. It was the one unbounded
/// <c>Channel&lt;T&gt;</c> left in the system — a slow/stuck
/// <c>ICachedCallLifecycleObserver</c> (a SQLite audit write) could not stretch
@@ -102,7 +102,7 @@ public static class StoreAndForwardSchema
// sort/scan step to satisfy that ordering on a large due-sweep. This index's
// leading (status, created_at) column order lets the planner walk matching
// rows already in created_at order and stop at LIMIT without touching
// non-pending rows or re-sorting (arch-review WP1.4). idx_sf_messages_status_due
// non-pending rows or re-sorting. idx_sf_messages_status_due
// is left in place — it still backs status+due-time lookups that don't order by
// created_at.
using (var orderIndex = connection.CreateCommand())
@@ -123,7 +123,7 @@ public class StoreAndForwardService
/// channel). Before <see cref="StartAsync"/> starts the pump, posts fall back
/// to inline processing (see <see cref="PostObserverNotification"/>).
/// <para>
/// WP2.6c: bounded (<see cref="StoreAndForwardOptions.ObserverQueueCapacity"/>,
/// Bounded (<see cref="StoreAndForwardOptions.ObserverQueueCapacity"/>,
/// default 10,000) with <see cref="BoundedChannelFullMode.DropOldest"/> — this was
/// the one unbounded channel left in the system; a pump that falls behind (a stuck
/// observer) now sheds the oldest unprocessed notification instead of growing
@@ -146,7 +146,7 @@ public class StoreAndForwardService
/// <summary>
/// Cumulative count of cached-call audit-observer notifications dropped because
/// <see cref="_observerQueue"/> was at capacity (WP2.6c). Not reset across
/// <see cref="_observerQueue"/> was at capacity. Not reset across
/// <see cref="StartAsync"/>/<see cref="StopAsync"/> cycles — a diagnostic total for
/// the lifetime of this service instance. Incremented unconditionally on every drop
/// by <see cref="LogObserverQueueDrop"/>, independent of that method's log throttling.
@@ -486,7 +486,7 @@ public class StoreAndForwardService
// StopAsync completes the channel, so a restarted instance needs a fresh
// one. The pump is best-effort: an observer that throws is logged and
// swallowed so a failing audit pipeline never corrupts retry bookkeeping.
// WP2.6c: bounded + DropOldest, sized from options; a drop increments
// Bounded + DropOldest, sized from options; a drop increments
// _observerQueueDroppedCount (surfaced via ObserverQueueDroppedCount) and is
// logged at Warning so a stuck observer is visible, not just silently lossy.
// F3: logging itself is rate-limited by LogObserverQueueDrop (first-drop Warning