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
@@ -23,7 +23,7 @@ public static class BrowserTime
    /// <param name="browserUtcOffsetMinutes">
    /// The value of JavaScript <c>new Date().getTimezoneOffset()</c>: the number
    /// of minutes that, <b>added</b> to local time, yields UTC. It is positive
-    /// for time zones behind UTC (e.g. +300 for UTC-5) and negative for zones
+    /// for time zones behind UTC (e.g. +300 for five hours behind UTC) and negative for zones
    /// ahead (e.g. -120 for UTC+2).
    /// </param>
    /// <returns>The equivalent instant in UTC, or <c>null</c> when the input is null.</returns>
@@ -79,7 +79,7 @@ public partial class FlowDebugger : ComponentBase, IDisposable
    [Inject] private ISiteRepository SiteRepository { get; set; } = default!;
    /// <summary>
    /// Resolves <c>{"$ref":"lib:Name"}</c> nodes in a method's parameter schema so the raw-JSON
-    /// escape hatch validates against the same resolved shape the form renders (#37).
+    /// escape hatch validates against the same resolved shape the form renders.
    /// </summary>
    [Inject] private ISchemaLibraryQueryService SchemaLibrary { get; set; } = default!;
    [Inject] private SiteScopeService SiteScope { get; set; } = default!;
@@ -154,7 +154,7 @@ public partial class FlowDebugger : ComponentBase, IDisposable
    private bool _scriptParamsValid;

    /// <summary>
-    /// Method entry (#37): the chosen method's resolved root schema (null when it declares no
+    /// Method entry: the chosen method's resolved root schema (null when it declares no
    /// parameters or the definitions do not parse) and its top-level fields — the card renders
    /// only when there is at least one. The values live in <see cref="_methodParams"/>, the same
    /// coerced value tree <c>ParameterValueForm</c> emits for the script pane, so the request
@@ -166,7 +166,7 @@ public partial class FlowDebugger : ComponentBase, IDisposable
    private bool _methodParamsValid;

    /// <summary>
-    /// Raw-JSON escape hatch for the whole method payload (#37): paste the exact body an
+    /// Raw-JSON escape hatch for the whole method payload: paste the exact body an
    /// external caller would send. The text is parsed and schema-validated on every edit;
    /// only a valid document reaches <see cref="_methodParams"/>, which stays the single source
    /// of truth in both modes.
@@ -214,6 +214,8 @@ public partial class FlowDebugger : ComponentBase, IDisposable
    /// on a step are NOT here — they are reported separately as
    /// <see cref="FlowGraph.UnattachedLogLines"/>.
    /// </summary>
+    /// <param name="graph">The flow graph to count log lines in, or null.</param>
+    /// <returns>The error, warning, info and total log-line counts.</returns>
    internal static (int Errors, int Warnings, int Info, int Total) CountLogs(FlowGraph? graph)
    {
        if (graph is null)
@@ -706,7 +708,7 @@ public partial class FlowDebugger : ComponentBase, IDisposable
        // row the run did not already have, the page is no longer short of lines and the flag
        // clears. Until then it stays: the site's rows reach central's audit store by telemetry
        // 5-30 s later, so a refresh that adds nothing proves nothing.
-        // Final review M7: read the OUTCOME's own flag — FlowDebugService copies the raw result's
+        // Read the OUTCOME's own flag — FlowDebugService copies the raw result's
        // onto it precisely so a caller need not unwrap Raw, and reading Raw here left the record
        // member with no consumer.
        var logsTruncated = (_raw.LogsTruncated || outcome.LogsTruncated)
@@ -721,6 +723,9 @@ public partial class FlowDebugger : ComponentBase, IDisposable
        => events?.Count(FlowStepProjector.IsLogLine) ?? 0;

    /// <summary>Preserves fresh Replay order, then appends live-only rows; duplicate event IDs use the fresh copy.</summary>
+    /// <param name="known">Events already held by the page, or null.</param>
+    /// <param name="fresh">Newly read Replay events, or null.</param>
+    /// <returns>The merged event list.</returns>
    internal static IReadOnlyList<AuditEvent> MergeEvents(IReadOnlyList<AuditEvent>? known, IReadOnlyList<AuditEvent>? fresh)
    {
        var byId = new Dictionary<Guid, AuditEvent>();
@@ -852,7 +857,7 @@ public partial class FlowDebugger : ComponentBase, IDisposable
        return (await SiteScope.PermittedSiteIdsAsync()).Contains(site.Id);
    }

-    /// <inheritdoc/>
+    /// <summary>Cancels any pending outcome refresh when the component is disposed.</summary>
    public void Dispose() => CancelPendingRefresh();

    private async Task LoadReplayAsync()
@@ -972,7 +977,7 @@ public partial class FlowDebugger : ComponentBase, IDisposable
    }

    /// <summary>
-    /// Form ⇄ Raw JSON (#37). Entering raw mode seeds the editor from the current value tree so
+    /// Form ⇄ Raw JSON. Entering raw mode seeds the editor from the current value tree so
    /// the operator edits what the form would have sent; leaving it re-mounts the form over the
    /// last VALID tree (the form is keyed on the method, and it is not rendered while raw mode is
    /// on, so it mounts fresh and re-reports validity from the tree).
@@ -1054,6 +1059,7 @@ public partial class FlowDebugger : ComponentBase, IDisposable
    /// <c>ParameterValueForm</c> emits and what the raw editor parsed), or null when the method
    /// declares no parameters. Run is gated on validity, so nothing here re-checks the tree.
    /// </summary>
+    /// <returns>The serialized parameters, or null when the method declares none.</returns>
    internal JsonElement? BuildParameters()
        => _inputFields.Count == 0 ? null : JsonSerializer.SerializeToElement(_methodParams);

@@ -1062,6 +1068,7 @@ public partial class FlowDebugger : ComponentBase, IDisposable
    /// nothing. <c>ParameterValueForm</c> already emits the coerced value tree (scalars as
    /// bool/long/double/string, objects as dictionaries, lists as lists), so it serializes as-is.
    /// </summary>
+    /// <returns>The serialized parameters, or null when the form produced nothing.</returns>
    internal JsonElement? BuildScriptParameters()
        => _scriptParams.Count == 0 ? null : JsonSerializer.SerializeToElement(_scriptParams);

@@ -1092,7 +1099,7 @@ public partial class FlowDebugger : ComponentBase, IDisposable

    /// <summary>
    /// Restores a persisted value tree only when it still validates against the method's current
-    /// schema — a stale tree (the schema changed, or the pre-#37 flat string-per-field entry) is
+    /// schema — a stale tree (the schema changed, or the older flat string-per-field entry) is
    /// dropped rather than painted into the form as errors.
    /// </summary>
    private async Task RestoreInputsAsync(int methodId)
@@ -123,6 +123,10 @@ public partial class InstanceConfigure
    /// counts: it pins a reportable template alarm off for this instance, which is a
    /// real override and not the same as inheriting.
    /// </summary>
+    /// <param name="overrideJson">The override JSON entered in the modal, if any.</param>
+    /// <param name="priority">The priority override, if one was chosen.</param>
+    /// <param name="mesReportable">The MES-reportable override, if one was chosen.</param>
+    /// <returns><c>true</c> when the modal carries any override worth persisting; otherwise <c>false</c>.</returns>
    internal static bool HasOverrideDelta(string? overrideJson, int? priority, bool? mesReportable)
        => !string.IsNullOrWhiteSpace(overrideJson) || priority.HasValue || mesReportable.HasValue;

@@ -112,7 +112,7 @@ public partial class TransportImport : ComponentBase, IDisposable

    /// <summary>
    /// Guards <see cref="_session"/> together with <see cref="_disposed"/> (register row
-    /// 103, the P6-6 lesser instance — mirrors <c>DebugView</c>'s <c>_sessionLock</c>).
+    /// 103 — mirrors <c>DebugView</c>'s <c>_sessionLock</c>).
    /// <see cref="TryLoadAsync"/> awaits <see cref="IBundleImporter.LoadAsync"/>, and the
    /// circuit can be torn down inside that window; publishing the freshly-opened session
    /// and observing disposal must be one atomic step so exactly one side (this method or
@@ -258,7 +258,7 @@ public partial class TransportImport : ComponentBase, IDisposable
            var loaded = await BundleImporter.LoadAsync(
                stream, passphrase, CancellationToken.None, ClientAddress.ClientAddress);

-            // Register row 103 (P6-6 lesser instance): the component may have been
+            // Register row 103: the component may have been
            // disposed while LoadAsync was in flight (navigation away mid-upload).
            // Publish and re-check disposal atomically under _sessionLock so exactly
            // one side tears the freshly-opened session down.
@@ -278,9 +278,9 @@ public partial class TransportImport : ComponentBase, IDisposable
        }
        catch (ArgumentException)
        {
-            // Encrypted bundle, no passphrase supplied — caller advances to Step 2.
+            // Encrypted bundle, no passphrase supplied — caller advances to the passphrase step.
            // We deliberately do NOT set _errorMessage here; the page surfaces
-            // an empty Step-2 prompt instead.
+            // an empty passphrase prompt instead.
            _session = null;
            throw;
        }
@@ -977,7 +977,7 @@ public partial class TransportImport : ComponentBase, IDisposable
    /// Register row 103: the flag is set and the session taken under the same lock
    /// <see cref="TryLoadAsync"/> publishes through, so a <see cref="TryLoadAsync"/> still
    /// awaiting <see cref="IBundleImporter.LoadAsync"/> either hands the session over here
-    /// or abandons it itself — never neither (mirrors <c>DebugView</c>'s P6-6 fix).
+    /// or abandons it itself — never neither (mirrors <c>DebugView</c>'s fix).
    /// </para>
    /// </summary>
    public void Dispose()
@@ -138,6 +138,8 @@ public partial class FlowGraphView : ComponentBase
    }

    /// <summary>Formats a coordinate culture-invariantly.</summary>
+    /// <param name="v">The value to format.</param>
+    /// <returns>The value formatted with up to two decimals using the invariant culture.</returns>
    public static string F(double v) => v.ToString("0.##", CultureInfo.InvariantCulture);

    private string RenderedWidth => F(_layout.Width * Math.Max(0.1, Zoom));
@@ -199,6 +201,8 @@ public partial class FlowGraphView : ComponentBase
        => n.Step != null && n.Kind is FlowStepKind.ApiCall or FlowStepKind.DbCall or FlowStepKind.Notify;

    /// <summary>Pill wording for an outbound step's folded outcome (plan D3: the latest lifecycle row decides).</summary>
+    /// <param name="outcome">The folded outcome of the outbound step.</param>
+    /// <returns>The short pill label for the outcome.</returns>
    public static string PillText(FlowStepOutcome outcome) => outcome switch
    {
        FlowStepOutcome.Ok => "Ok",
@@ -224,6 +228,9 @@ public partial class FlowGraphView : ComponentBase
    /// sync database call's operation detail (<c>write · 3 rows</c>) kept in front of it. The projector's
    /// subtitle already leads with the audit status, which the pill now carries, so that head is dropped.
    /// </summary>
+    /// <param name="kind">The kind of the outbound step.</param>
+    /// <param name="subtitle">The step's projected subtitle, which may lead with the audit status.</param>
+    /// <returns>The mode text shown after the status pill.</returns>
    public static string OutboundMode(FlowStepKind kind, string? subtitle)
    {
        if (kind == FlowStepKind.Notify) return "notify";
@@ -243,6 +250,8 @@ public partial class FlowGraphView : ComponentBase
    /// everything else — <c>info</c>, <c>debug</c>, an unknown level — counts as info, so the badge
    /// never silently drops a line.
    /// </summary>
+    /// <param name="s">The step whose log lines are counted; may be null.</param>
+    /// <returns>The error, warning and info line counts.</returns>
    internal static (int Errors, int Warnings, int Info) LogCounts(FlowStep? s)
    {
        if (s?.Logs is not { Count: > 0 } lines) return (0, 0, 0);
@@ -260,6 +269,8 @@ public partial class FlowGraphView : ComponentBase
    }

    /// <summary>Hover text for the log badge — the non-zero levels only ("1 error, 2 warnings, 4 info").</summary>
+    /// <param name="counts">The per-severity log line counts.</param>
+    /// <returns>The hover text listing the non-zero levels.</returns>
    internal static string LogTitle((int Errors, int Warnings, int Info) counts)
    {
        var (errors, warnings, info) = counts;
@@ -273,12 +284,14 @@ public partial class FlowGraphView : ComponentBase
    /// <summary>
    /// The subtitle a failed or timed-out step shows instead of its own: <c>{Type}: {message}</c>, where
    /// the type is the exception's name without its namespace. Parsing is
-    /// <see cref="ExceptionHeader.Parse"/> (final review M1 — the same parser the step detail panel
+    /// <see cref="ExceptionHeader.Parse"/> (the same parser the step detail panel
    /// uses), which takes the first line of the captured <see cref="FlowStep.ErrorDetail"/> and follows
    /// its <c>" ---&gt; "</c> chain to the innermost exception. Falls back to the line itself when it
    /// carries no <c>": "</c>, and to <see cref="FlowStep.ErrorMessage"/> when there is no usable detail.
    /// Null for every non-failed step.
    /// </summary>
+    /// <param name="s">The step to build the subtitle for.</param>
+    /// <returns>The exception subtitle, or null for a step that did not fail.</returns>
    internal static string? ExceptionSubtitle(FlowStep s)
    {
        if (s.Outcome is not (FlowStepOutcome.Failed or FlowStepOutcome.TimedOut)) return null;
@@ -305,6 +318,8 @@ public partial class FlowGraphView : ComponentBase
    /// than one row — the submit→terminal wall time with a leading <c>+</c> (<c>+4.1 s</c>), since that
    /// span is elapsed time downstream of the script, not time the script spent (node anatomy).
    /// </summary>
+    /// <param name="n">The layout node to describe.</param>
+    /// <returns>The formatted duration text for the node's head row.</returns>
    public static string Duration(FlowLayoutNode n)
    {
        if (n.Step?.DurationMs is not int ms)
@@ -317,6 +332,9 @@ public partial class FlowGraphView : ComponentBase
    }

    /// <summary>Clips a gutter label to what fits, keeping the full text in a <c>title</c>.</summary>
+    /// <param name="text">The label text; may be null.</param>
+    /// <param name="max">The maximum number of characters to keep.</param>
+    /// <returns>The text, clipped to fit when it is longer than the maximum.</returns>
    public static string Clip(string? text, int max)
    {
        if (string.IsNullOrEmpty(text)) return string.Empty;
@@ -329,6 +347,8 @@ public partial class FlowGraphView : ComponentBase
    /// titles on the Tags lane are attribute paths that mostly differ in their last segment, so the
    /// shared head is shown once in the lane gutter and each node shows the tail that tells it apart.
    /// </summary>
+    /// <param name="titles">The node titles on the lane.</param>
+    /// <returns>The shared dotted prefix, or null when there is none worth showing.</returns>
    public static string? CommonDottedPrefix(IReadOnlyList<string> titles)
    {
        if (titles.Count < 2) return null;
@@ -352,6 +372,8 @@ public partial class FlowGraphView : ComponentBase
    /// camel-case boundaries so a wrapped title breaks at <c>DelmiaRecipe|Download</c> rather than
    /// mid-word; the browser still falls back to breaking anywhere for a single overlong segment.
    /// </summary>
+    /// <param name="text">The title text; may be null.</param>
+    /// <returns>The text with zero-width spaces inserted at preferred break points.</returns>
    public static string WrapHints(string? text)
    {
        if (string.IsNullOrEmpty(text)) return string.Empty;
@@ -373,6 +395,9 @@ public partial class FlowGraphView : ComponentBase
    /// Removes <paramref name="prefix"/> where it starts <paramref name="text"/> or a comma-separated
    /// item within it (the write subtitle is <c>a.X = 1, a.Y = 2</c>); null/empty text passes through.
    /// </summary>
+    /// <param name="text">The text to strip; may be null.</param>
+    /// <param name="prefix">The prefix to remove; may be null.</param>
+    /// <returns>The text with the prefix removed.</returns>
    public static string? StripPrefix(string? text, string? prefix)
    {
        if (string.IsNullOrEmpty(text) || string.IsNullOrEmpty(prefix)) return text;
@@ -385,6 +410,14 @@ public partial class FlowGraphView : ComponentBase
    /// <c>&lt;text&gt;</c> tag for its own markup-mode switch and refuses attributes on it,
    /// so the SVG element of the same name cannot be written literally inside a code block.
    /// </summary>
+    /// <param name="x">The x coordinate.</param>
+    /// <param name="y">The y coordinate.</param>
+    /// <param name="cssClass">The CSS class for the element.</param>
+    /// <param name="content">The text content, encoded by this method.</param>
+    /// <param name="anchor">The optional <c>text-anchor</c> value.</param>
+    /// <param name="title">The optional tooltip title.</param>
+    /// <param name="dataTest">The optional <c>data-test</c> attribute value.</param>
+    /// <returns>The encoded SVG text element markup.</returns>
    public static MarkupString SvgText(string x, string y, string cssClass, string content, string? anchor = null, string? title = null, string? dataTest = null)
    {
        var sb = new StringBuilder("<text x=\"").Append(x).Append("\" y=\"").Append(y).Append("\" class=\"").Append(cssClass).Append('"');
@@ -427,6 +460,10 @@ public partial class FlowGraphView : ComponentBase
    /// draws from <paramref name="a"/> to <paramref name="b"/> (the middle of a same-lane straight line).
    /// Kept in step with those two path builders.
    /// </summary>
+    /// <param name="a">The source node.</param>
+    /// <param name="b">The target node.</param>
+    /// <param name="isAsync">True when the connector is an async branch.</param>
+    /// <returns>The midpoint of the connector's vertical run.</returns>
    public static (double X, double Y) SpawnBadgePoint(FlowLayoutNode a, FlowLayoutNode b, bool isAsync)
    {
        var x1 = a.X + NodeWidth;
@@ -460,6 +497,7 @@ public partial class FlowGraphView : ComponentBase
    /// </summary>
    /// <param name="graph">The real graph, or null.</param>
    /// <param name="predicted">The prediction, or null.</param>
+    /// <returns>The computed layout.</returns>
    public static FlowLayout ComputeLayout(FlowGraph? graph, PredictedFlow? predicted)
    {
        var hasReal = graph is { Steps.Count: > 0 };
@@ -652,6 +690,8 @@ public partial class FlowGraphView : ComponentBase
    /// up to <see cref="ExternalSublabelTargets"/> named, the rest folded into <c>+n</c>
    /// (<c>Delmia.AckRecipe · MesDb · Planners +1</c>). Empty when the lane is unused.
    /// </summary>
+    /// <param name="distinctTargets">The distinct external targets in first-seen order.</param>
+    /// <returns>The gutter sublabel text.</returns>
    public static string ExternalSublabel(IReadOnlyList<string> distinctTargets)
    {
        if (distinctTargets.Count == 0) return string.Empty;
@@ -666,6 +706,9 @@ public partial class FlowGraphView : ComponentBase
    /// crosses a node sitting between the two lanes. Falls back to <see cref="OrthogonalPath"/> when
    /// the target is not below the source.
    /// </summary>
+    /// <param name="a">The source node.</param>
+    /// <param name="b">The target node.</param>
+    /// <returns>The SVG path data for the connector.</returns>
    public static string AsyncPath(FlowLayoutNode a, FlowLayoutNode b)
    {
        if (b.Y <= a.Y)
@@ -682,6 +725,9 @@ public partial class FlowGraphView : ComponentBase
    /// of <paramref name="b"/>: straight when in the same lane, otherwise right-down/up-right
    /// through the inter-column gap. A backwards edge (target left of source) loops under.
    /// </summary>
+    /// <param name="a">The source node.</param>
+    /// <param name="b">The target node.</param>
+    /// <returns>The SVG path data for the connector.</returns>
    public static string OrthogonalPath(FlowLayoutNode a, FlowLayoutNode b)
    {
        var x1 = a.X + NodeWidth;
@@ -58,8 +58,8 @@ public interface IDialogService
    /// button's styling.</param>
    /// <param name="confirmLabel">Verb rendered on the confirm button. Only
    /// <see cref="DialogSeverity.Destructive"/> falls back to "Delete" when this is
-    /// blank; the other severities fall back to "Confirm". The row-28 rule still
-    /// applies — name the action.</param>
+    /// blank; the other severities fall back to "Confirm". The rule to name the
+    /// action still applies.</param>
    /// <returns>A task that resolves to <c>true</c> when the user confirms, or <c>false</c> when cancelled.</returns>
    Task<bool> ConfirmAsync(string title, string message, DialogSeverity severity, string? confirmLabel = null);