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.
2026-10-07 14:12:25 -04:00
parent 3a217b9484
commit 0ffd4bdbea
217 changed files with 1224 additions and 695 deletions
@@ -292,6 +292,7 @@ public interface IAuditLogRepository
    /// </remarks>
    /// <param name="executionId">Any execution id in the chain; the implementation walks to the root and back down.</param>
    /// <param name="ct">Cancellation token.</param>
+    /// <param name="permittedSiteIds">Optional site scope restricting which sites' rows are visible; <c>null</c> means unrestricted.</param>
    /// <returns>A task that resolves to the full execution tree rooted at the topmost ancestor, one node per distinct execution.</returns>
    Task<IReadOnlyList<ExecutionTreeNode>> GetExecutionTreeAsync(
        Guid executionId,
@@ -307,6 +308,7 @@ public interface IAuditLogRepository
    /// </summary>
    /// <param name="executionId">Any execution id in the chain.</param>
    /// <param name="ct">Cancellation token.</param>
+    /// <param name="permittedSiteIds">Optional site scope restricting which sites' rows are visible; <c>null</c> means unrestricted.</param>
    /// <returns>The canonical audit events that make up the flow, oldest first.</returns>
    Task<IReadOnlyList<AuditEvent>> GetTraceEventsAsync(
        Guid executionId,
@@ -93,7 +93,7 @@ public interface INotificationOutboxRepository
    /// is its own transaction.
    /// </summary>
    /// <remarks>
-    /// <b>Why this exists (arch-review 2026-08-19 P5-4).</b> The operator retry/
+    /// <b>Why this exists.</b> The operator retry/
    /// discard handlers are read-check-write across two round trips:
    /// <see cref="GetByIdAsync"/> reads the row, the handler checks its
    /// in-memory <c>Status</c>, then a write persists the transition. A detached
@@ -93,7 +93,7 @@ public interface ISecuredWriteRepository
    /// the compare-and-swap guard for the approve-vs-reject race: a stale-read reject
    /// used to land a blind full-row update while a concurrent approve's multi-second
    /// site relay was still in flight, marking the row <c>Rejected</c> while the plant
-    /// write physically executed (arch-review 2026-08-19 P6-1). The conditional
+    /// write physically executed. The conditional
    /// <c>WHERE Status='Pending'</c> makes exactly one of approve/reject/expiry win.
    /// The loser observes <c>false</c> and must record nothing — no status change and no
    /// reject audit row.
@@ -252,6 +252,12 @@ public interface ITemplateEngineRepository
    Task<IReadOnlyList<Instance>> GetInstancesBySiteIdAsync(int siteId, CancellationToken cancellationToken = default);

    /// <summary>Reads one bounded, untracked page of topology instance rows for a site/area.</summary>
+    /// <param name="siteId">The site ID.</param>
+    /// <param name="areaId">The area ID to filter by, or null for every area.</param>
+    /// <param name="skip">The number of rows to skip.</param>
+    /// <param name="take">The maximum number of rows to return.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A task that resolves to a read-only page of instances.</returns>
    Task<IReadOnlyList<Instance>> GetTopologyInstancesAsync(int siteId, int? areaId, int skip, int take, CancellationToken cancellationToken = default);

    /// <summary>Retrieves an instance by unique name.</summary>
@@ -4,6 +4,8 @@ namespace ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Services;
 public interface IConfigurationCommandTransaction
 {
    /// <summary>Each database retry supplies a fresh scope; the operation must not perform external side effects.</summary>
+    /// <param name="operation">The database-only operation to run within the transaction.</param>
+    /// <returns>The operation's result, if any.</returns>
    Task<object?> ExecuteAsync(Func<IServiceProvider, Task<object?>> operation);
 }

@@ -11,6 +13,7 @@ public interface IConfigurationCommandTransaction
 public interface IConfigurationCommitActions
 {
    /// <summary>Queues an idempotent local maintenance action.</summary>
+    /// <param name="action">The action to run after a successful commit.</param>
    void Add(Func<Task> action);
 }

@@ -2,5 +2,9 @@ namespace ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Services;
 /// <summary>Private worker handoff for an existing configured SQL connection. Never log or expose the returned secret.</summary>
 public interface ISandboxDatabaseConnectionSource
 {
+    /// <summary>Resolves the connection string for a configured connection.</summary>
+    /// <param name="connectionName">The configured database connection name.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The connection string; a secret that must never be logged or exposed.</returns>
    Task<string> GetSandboxConnectionStringAsync(string connectionName, CancellationToken cancellationToken);
 }
@@ -110,7 +110,7 @@ public interface ISiteAuditQueue
    /// <param name="sinceUtc">Lower bound timestamp (UTC).</param>
    /// <param name="batchSize">Maximum number of rows to return.</param>
    /// <param name="afterId">
-    /// Composite-keyset tiebreak cursor (WP2.3), mirroring
+    /// Composite-keyset tiebreak cursor, mirroring
    /// <see cref="IOperationTrackingStore.ReadChangedSinceAsync"/>: when non-null it is the
    /// <see cref="AuditEvent.EventId"/> ("D" GUID form) of the last row already consumed at
    /// <paramref name="sinceUtc"/>, and only rows strictly after the composite
@@ -125,7 +125,7 @@ public interface ISiteAuditQueue
        DateTime sinceUtc, int batchSize, string? afterId = null, CancellationToken ct = default);

    /// <summary>
-    /// Reconciliation-pull commit surface, cursor form (WP2.3): flips every row at or before
+    /// Reconciliation-pull commit surface, cursor form: flips every row at or before
    /// the composite cursor <c>(<paramref name="sinceUtc"/>, <paramref name="afterId"/>)</c>
    /// from <see cref="ZB.MOM.WW.ScadaBridge.Commons.Types.Enums.AuditForwardState.Pending"/>/
    /// <see cref="ZB.MOM.WW.ScadaBridge.Commons.Types.Enums.AuditForwardState.Forwarded"/> to
@@ -231,6 +231,12 @@ public interface ISiteAuditQueue
    /// <c>(OccurredAtUtc, EventId)</c>, at most <paramref name="limit"/> rows. Independent of
    /// forwarding state — moves no cursor and flips nothing. At most 64 ids per call.
    /// </summary>
+    /// <param name="executionIds">Execution ids to match against <c>ExecutionId</c> or <c>ParentExecutionId</c>.</param>
+    /// <param name="sinceUtc">Lower bound on <c>OccurredAtUtc</c> (UTC).</param>
+    /// <param name="limit">Maximum number of rows to return.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <param name="afterEventId">Optional <c>EventId</c> keyset cursor for paging past rows already consumed.</param>
+    /// <returns>A task that resolves to the matching audit events ordered by <c>(OccurredAtUtc, EventId)</c>.</returns>
    Task<IReadOnlyList<AuditEvent>> ReadByExecutionIdsAsync(
        IReadOnlyCollection<Guid> executionIds, DateTime sinceUtc, int limit, CancellationToken ct = default, string? afterEventId = null);
 }