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
@@ -170,7 +170,7 @@ public sealed class ArtifactDiff
// previewed as "Identical". Mirrors CompareDatabaseConnection below.
AddIfDifferent(changes, "MaxRetries", existing.MaxRetries, incoming.MaxRetries);
AddIfDifferent(changes, "RetryDelay", existing.RetryDelay.ToString(), incoming.RetryDelay.ToString());
// arch-review 2026-08-19 P7-1 (row-27 shape): TimeoutSeconds is operative at
// TimeoutSeconds is operative at
// runtime and the importer has always APPLIED it, but the diff omitted it — same
// "silently changed and invisible to preview" defect as the MaxRetries fix above.
// A null incoming value (bundle written before this field existed) compares as
@@ -1764,17 +1764,6 @@ public sealed class BundleImporter : IBundleImporter
}
/// <inheritdoc />
/// <remarks>
/// Register row 43: every abandonment path (Central UI wizard reset /
/// back-to-upload / circuit teardown, CLI preview, CLI import that aborts
/// before Apply) funnels here so a session that will never be applied stops
/// holding one of the <c>MaxConcurrentImportSessions</c> slots — and stops
/// holding its decrypted plaintext — for the rest of its TTL. Applies the same
/// zero-then-remove ordering as the T-007 release inside
/// <see cref="ApplyAsync"/>: zeroing first means a caller still holding the
/// session reference (the Razor page keeps one for the Result step) observes
/// the cleared buffer too.
/// </remarks>
public void Abandon(Guid sessionId)
{
// Get() returns null for an unknown or already-expired id, which makes the
@@ -58,28 +58,22 @@ internal sealed class BundleSessionEvictionService : BackgroundService
_openSessionCountProvider = () => _sessionStore.OpenSessionCount;
}
/// <summary>
/// Register row 53: registers the open-import-sessions gauge provider before the
/// sweep loop starts. This service is the Transport component's only lifecycle seam
/// (the session store itself is a plain singleton), and it is registered by
/// <c>AddTransport</c>, which only the Central branch of the host calls — so the
/// gauge reports 0 on a site node, where there are no import sessions to count.
/// </summary>
/// <param name="cancellationToken">Host startup cancellation token.</param>
/// <returns>A task that completes when the base <see cref="BackgroundService"/> has started.</returns>
// Registers the open-import-sessions gauge provider before the
// sweep loop starts. This service is the Transport component's only lifecycle seam
// (the session store itself is a plain singleton), and it is registered by
// AddTransport, which only the Central branch of the host calls — so the
// gauge reports 0 on a site node, where there are no import sessions to count.
/// <inheritdoc />
public override Task StartAsync(CancellationToken cancellationToken)
{
ScadaBridgeTelemetry.SetImportSessionCountProvider(_openSessionCountProvider);
return base.StartAsync(cancellationToken);
}
/// <summary>
/// Deregisters this instance's gauge provider on graceful stop so the gauge falls
/// back to 0 rather than reading through a dead store. The clear is identity-checked,
/// so a late stop cannot clobber a successor that already re-registered.
/// </summary>
/// <param name="cancellationToken">Host shutdown cancellation token.</param>
/// <returns>A task that completes when the base <see cref="BackgroundService"/> has stopped.</returns>
// Deregisters this instance's gauge provider on graceful stop so the gauge falls
// back to 0 rather than reading through a dead store. The clear is identity-checked,
// so a late stop cannot clobber a successor that already re-registered.
/// <inheritdoc />
public override async Task StopAsync(CancellationToken cancellationToken)
{
ScadaBridgeTelemetry.ClearImportSessionCountProvider(_openSessionCountProvider);
@@ -256,7 +256,7 @@ public sealed record ExternalSystemDto(
TimeSpan RetryDelay,
IReadOnlyList<ExternalSystemMethodDto> Methods,
SecretsBlock? Secrets,
// Per-system HTTP round-trip timeout (arch-review 2026-08-19 P7-1, row-27 shape).
// Per-system HTTP round-trip timeout (arch-review 2026-08-19).
// Additive trailing field; null distinguishes a bundle written before this field
// existed from a bundle that explicitly carries the entity's own "0 = unset"
// sentinel. BundleImporter treats a null incoming value as "not specified by this