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
@@ -96,12 +96,16 @@ public sealed class FlowDebugRunner
private readonly Func<DateTimeOffset> _now;
/// <summary>Creates the runner.</summary>
/// <param name="logger">Logger for run diagnostics.</param>
public FlowDebugRunner(ILogger<FlowDebugRunner> logger)
: this(logger, Task.Delay, () => DateTimeOffset.UtcNow)
{
}
/// <summary>Creates the runner with an injectable delay and clock (tests).</summary>
/// <param name="logger">Logger for run diagnostics.</param>
/// <param name="delay">Delay function used for polling waits.</param>
/// <param name="now">Clock returning the current UTC time.</param>
public FlowDebugRunner(
ILogger<FlowDebugRunner> logger,
Func<TimeSpan, CancellationToken, Task> delay,
@@ -125,6 +129,11 @@ public sealed class FlowDebugRunner
/// registered none (a test composition root) collects raw but is still capped.
/// </para>
/// </summary>
/// <param name="sp">The request-scoped service provider.</param>
/// <param name="cmd">The command to execute.</param>
/// <param name="user">The authenticated operator.</param>
/// <param name="ct">Cancellation token.</param>
/// <returns>The run result with the collected trace rows.</returns>
public Task<FlowDebugRunResult> RunMethodAsync(
IServiceProvider sp, FlowDebugRunMethodCommand cmd, AuthenticatedUser user, CancellationToken ct)
=> WithinCommandBudgetAsync(sp, (deadline, token) => RunMethodCoreAsync(sp, cmd, user, deadline, token), ct);
@@ -233,6 +242,11 @@ public sealed class FlowDebugRunner
/// Live run of a value-change trigger (design §5.3/§5.4): traced routed write through the
/// site's normal path, then poll the site's trace rows for the spawned run(s).
/// </summary>
/// <param name="sp">The request-scoped service provider.</param>
/// <param name="cmd">The command to execute.</param>
/// <param name="user">The authenticated operator.</param>
/// <param name="ct">Cancellation token.</param>
/// <returns>The run result with the collected trace rows.</returns>
public Task<FlowDebugRunResult> RunValueChangeAsync(
IServiceProvider sp, FlowDebugRunValueChangeCommand cmd, AuthenticatedUser user, CancellationToken ct)
=> WithinCommandBudgetAsync(sp, (deadline, token) => RunValueChangeCoreAsync(sp, cmd, user, deadline, token), ct);
@@ -269,6 +283,11 @@ public sealed class FlowDebugRunner
/// rather than through <see cref="RouteHelper"/> is deliberate: the helper emits its own
/// always-on RouteCall row with no operator actor, which would give the graph two roots.
/// </summary>
/// <param name="sp">The request-scoped service provider.</param>
/// <param name="cmd">The command to execute.</param>
/// <param name="user">The authenticated operator.</param>
/// <param name="ct">Cancellation token.</param>
/// <returns>The run result with the collected trace rows.</returns>
public Task<FlowDebugRunResult> RunScriptAsync(
IServiceProvider sp, FlowDebugRunScriptCommand cmd, AuthenticatedUser user, CancellationToken ct)
=> WithinCommandBudgetAsync(sp, (deadline, token) => RunScriptCoreAsync(sp, cmd, user, deadline, token), ct);
@@ -570,6 +589,11 @@ public sealed class FlowDebugRunner
}
/// <summary>Replay (design §7.1): the stored ScriptTrace chain for any execution id.</summary>
/// <param name="sp">The request-scoped service provider.</param>
/// <param name="cmd">The replay command naming the execution.</param>
/// <param name="ct">Cancellation token.</param>
/// <param name="user">The authenticated operator.</param>
/// <returns>The reconstructed run result read from the stored trace rows.</returns>
public async Task<FlowDebugRunResult> ReplayAsync(
IServiceProvider sp, FlowDebugReplayCommand cmd, CancellationToken ct, AuthenticatedUser user)
{
@@ -627,8 +651,11 @@ public sealed class FlowDebugRunner
private sealed class TraceReadBatch(Guid[] executionIds, DateTime sinceUtc)
{
/// <summary>Execution ids whose trace rows are being read.</summary>
public Guid[] ExecutionIds { get; } = executionIds;
/// <summary>Lower bound (UTC) for the next read.</summary>
public DateTime SinceUtc { get; set; } = sinceUtc;
/// <summary>Keyset cursor: the last event id already consumed, or null.</summary>
public string? AfterEventId { get; set; }
}