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
@@ -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);