docs(tests): fix CommentChecker findings across tests/ — 13,392 → 0 (repo-wide scan clean)

Comment/XML-doc changes only: - add summaries to ~10k test methods, fixtures, fakes and helpers (+ <param> on theories, <returns> on async Task methods, <inheritdoc/> on interface implementations the checker can resolve) - strip ~2.6k project-tracking references (WP*, P*-*, row-NN, Task N, #NN, Component-0NN) from comments, keeping the explanatory text; reword false positives in comments only - real docs on fakes implementing BCL/library interfaces (IDisposable, ILogger, IOptionsMonitor, IAsyncLifetime) - reword the last 5 src/ false positives (CWE-1236, failures-1, year-0001, M365) Only non-comment edits: four one-line nested classes split across lines so members can carry docs. Build 0 errors / 0 warnings.
2026-10-07 15:05:49 -04:00
parent 0ffd4bdbea
commit 513fa1aa16
998 changed files with 17896 additions and 2395 deletions
@@ -14,6 +14,7 @@ public class DebugTreeBuilderTests
    private static AttributeValueChanged Attr(string name, object? value = null, string quality = "Good")
        => new("Inst", name, name, value, quality, DateTimeOffset.UtcNow);

+    /// <summary>Verifies that a root-level attribute becomes a single leaf.</summary>
    [Fact]
    public void RootLevelAttribute_BecomesSingleLeaf()
    {
@@ -27,6 +28,7 @@ public class DebugTreeBuilderTests
        Assert.Equal("Speed", node.Attribute!.AttributeName);
    }

+    /// <summary>Verifies two sibling leaves share single branch sorted by segment.</summary>
    [Fact]
    public void TwoSiblingLeaves_ShareSingleBranch_SortedBySegment()
    {
@@ -47,6 +49,7 @@ public class DebugTreeBuilderTests
        Assert.Equal("Temp", branch.Children[1].Segment);
    }

+    /// <summary>Verifies that a deep path nests branches by accumulated prefix.</summary>
    [Fact]
    public void DeepPath_NestsBranchesByAccumulatedPrefix()
    {
@@ -70,6 +73,7 @@ public class DebugTreeBuilderTests
        Assert.NotNull(pump.Attribute);
    }

+    /// <summary>Verifies that branches are deduplicated across deep paths sharing a prefix.</summary>
    [Fact]
    public void BranchDedupe_SharedPrefixAcrossDeepPaths()
    {
@@ -95,6 +99,7 @@ public class DebugTreeBuilderTests
        Assert.Equal("Motor1.Compressor.Valve", compressor.Children[1].Key);
    }

+    /// <summary>Verifies that a bad-quality descendant marks all ancestor branches as bad.</summary>
    [Fact]
    public void RollUp_BadQualityDescendant_MarksAllAncestorBranches()
    {
@@ -113,6 +118,7 @@ public class DebugTreeBuilderTests
        Assert.True(compressor.HasBadQuality);
    }

+    /// <summary>Verifies that a branch whose leaves are all good is not marked as bad quality.</summary>
    [Fact]
    public void RollUp_AllGood_LeavesBranchHasBadQualityFalse()
    {
@@ -123,6 +129,8 @@ public class DebugTreeBuilderTests
        Assert.False(motor.HasBadQuality);
    }

+    /// <summary>Verifies that any non-good quality counts as bad when rolling up.</summary>
+    /// <param name="quality">The test input.</param>
    [Theory]
    [InlineData("Uncertain")]
    [InlineData("Bad")]
@@ -134,6 +142,7 @@ public class DebugTreeBuilderTests
        Assert.True(Assert.Single(tree).HasBadQuality);
    }

+    /// <summary>Verifies that filtering keeps only the matching leaves and their ancestors.</summary>
    [Fact]
    public void Filter_KeepsOnlyMatchingLeaves_AndTheirAncestors()
    {
@@ -153,6 +162,7 @@ public class DebugTreeBuilderTests
        Assert.Equal("Motor1.Temp", leaf.Key);
    }

+    /// <summary>Verifies that filtering is case insensitive.</summary>
    [Fact]
    public void Filter_IsCaseInsensitive()
    {
@@ -163,6 +173,8 @@ public class DebugTreeBuilderTests
        Assert.Equal("Motor1.Temp", Assert.Single(motor.Children).Key);
    }

+    /// <summary>Verifies that an empty or whitespace filter returns the full forest.</summary>
+    /// <param name="filter">The test input.</param>
    [Theory]
    [InlineData(null)]
    [InlineData("")]
@@ -177,6 +189,7 @@ public class DebugTreeBuilderTests
        Assert.Equal("Motor2", tree[1].Key);
    }

+    /// <summary>Verifies that a filter with no matches returns an empty forest.</summary>
    [Fact]
    public void Filter_NoMatches_ReturnsEmptyForest()
    {
@@ -186,6 +199,7 @@ public class DebugTreeBuilderTests
        Assert.Empty(tree);
    }

+    /// <summary>Verifies that the top-level forest is sorted by segment.</summary>
    [Fact]
    public void TopLevelForest_SortedBySegment()
    {
@@ -198,6 +212,7 @@ public class DebugTreeBuilderTests
        Assert.Equal("Zeta", tree[2].Key);
    }

+    /// <summary>Verifies that empty input returns an empty forest.</summary>
    [Fact]
    public void EmptyInput_ReturnsEmptyForest()
    {
@@ -205,6 +220,7 @@ public class DebugTreeBuilderTests
        Assert.Empty(tree);
    }

+    /// <summary>Verifies that bad quality four levels deep rolls up to the root.</summary>
    [Fact]
    public void RollUp_FourLevelDeepBadQuality_ReachesRoot()
    {
@@ -221,6 +237,7 @@ public class DebugTreeBuilderTests
        Assert.True(d.HasBadQuality);
    }

+    /// <summary>Verifies that a filter matching a deep leaf retains all its ancestor branches.</summary>
    [Fact]
    public void Filter_DeepLeafMatch_RetainsAllAncestorBranches()
    {
@@ -235,7 +252,7 @@ public class DebugTreeBuilderTests
    }

    // ---------------------------------------------------------------------
-    // DV-4: BuildAlarmTree — computed leaves, native condition groupings,
+    // BuildAlarmTree — computed leaves, native condition groupings,
    // configured-placeholder binding nodes, roll-up, filter.
    // ---------------------------------------------------------------------

@@ -261,6 +278,7 @@ public class DebugTreeBuilderTests
            IsConfiguredPlaceholder = placeholder,
        };

+    /// <summary>Verifies that a computed alarm with a path-qualified name becomes a leaf under a branch.</summary>
    [Fact]
    public void Computed_PathQualifiedName_BecomesLeafUnderBranch()
    {
@@ -282,6 +300,7 @@ public class DebugTreeBuilderTests
        Assert.Equal("Motor1.HighTemp", leaf.Alarm!.AlarmName);
    }

+    /// <summary>Verifies that a computed alarm with a root-level name becomes a single leaf.</summary>
    [Fact]
    public void Computed_RootLevelName_BecomesSingleLeaf()
    {
@@ -294,6 +313,7 @@ public class DebugTreeBuilderTests
        Assert.NotNull(node.Alarm);
    }

+    /// <summary>Verifies that a native condition nests under its binding node with the source reference segment.</summary>
    [Fact]
    public void Native_Condition_NestsUnderBindingNode_WithSourceReferenceSegment()
    {
@@ -318,6 +338,7 @@ public class DebugTreeBuilderTests
        Assert.Equal("Tank1.Level.HiHi", condition.Alarm!.SourceReference);
    }

+    /// <summary>Verifies that two native conditions share the same binding node.</summary>
    [Fact]
    public void Native_TwoConditions_ShareSameBindingNode()
    {
@@ -340,6 +361,7 @@ public class DebugTreeBuilderTests
        Assert.Equal("Tank1.Levels::Tank1.Level.LoLo", binding.Children[1].Key);
    }

+    /// <summary>Verifies that a native placeholder yields a binding node without children.</summary>
    [Fact]
    public void Native_Placeholder_YieldsChildlessBindingNode()
    {
@@ -354,10 +376,11 @@ public class DebugTreeBuilderTests
        Assert.Empty(binding.Children);
    }

+    /// <summary>Verifies that real conditions win over a placeholder under the same native binding.</summary>
    [Fact]
    public void Native_PlaceholderAndRealConditions_RealConditionsWin()
    {
-        // DV-2 shouldn't emit both, but be safe: placeholder adds nothing.
+        // Shouldn't emit both, but be safe: placeholder adds nothing.
        var tree = DebugTreeBuilder.BuildAlarmTree(
            new[]
            {
@@ -373,6 +396,7 @@ public class DebugTreeBuilderTests
        Assert.Equal("Tank1.Levels::Tank1.Level.HiHi", condition.Key);
    }

+    /// <summary>Verifies that an active descendant sets the worst state to active and is counted when rolling up.</summary>
    [Fact]
    public void RollUp_ActiveDescendant_SetsWorstStateActiveAndCounts()
    {
@@ -394,6 +418,7 @@ public class DebugTreeBuilderTests
        Assert.Equal(1, binding.ActiveCount);
    }

+    /// <summary>Verifies that when every alarm is normal the worst state is normal with a zero active count.</summary>
    [Fact]
    public void RollUp_AllNormal_WorstStateNormalAndZeroCount()
    {
@@ -405,6 +430,7 @@ public class DebugTreeBuilderTests
        Assert.Equal(0, tank.ActiveCount);
    }

+    /// <summary>Verifies that a placeholder never counts as active when rolling up.</summary>
    [Fact]
    public void RollUp_Placeholder_NeverCountsAsActive()
    {
@@ -423,6 +449,7 @@ public class DebugTreeBuilderTests
        Assert.Equal(0, binding.ActiveCount);
    }

+    /// <summary>Verifies that filtering on the source reference keeps the condition under its binding and ancestors.</summary>
    [Fact]
    public void Filter_OnSourceReference_KeepsConditionUnderBindingAndAncestors()
    {
@@ -443,6 +470,7 @@ public class DebugTreeBuilderTests
        Assert.Equal("Tank1.Levels::Tank1.Level.HiHi", condition.Key);
    }

+    /// <summary>Verifies that filtering on a binding canonical name keeps the binding node.</summary>
    [Fact]
    public void Filter_OnBindingCanonicalName_KeepsBindingNode()
    {
@@ -463,6 +491,7 @@ public class DebugTreeBuilderTests
        Assert.Single(binding.Children);
    }

+    /// <summary>Verifies that filtering on a binding name that matches a placeholder keeps the binding node.</summary>
    [Fact]
    public void Filter_OnBindingName_MatchingPlaceholder_KeepsBindingNode()
    {
@@ -477,6 +506,7 @@ public class DebugTreeBuilderTests
        Assert.False(binding.HasChildren);
    }

+    /// <summary>Verifies that filtering on a computed alarm name is case insensitive.</summary>
    [Fact]
    public void Filter_OnComputedAlarmName_IsCaseInsensitive()
    {
@@ -488,6 +518,8 @@ public class DebugTreeBuilderTests
        Assert.Equal("Motor1.HighTemp", Assert.Single(motor.Children).Key);
    }

+    /// <summary>Verifies that an empty or whitespace filter returns the full alarm forest.</summary>
+    /// <param name="filter">The test input.</param>
    [Theory]
    [InlineData(null)]
    [InlineData("")]
@@ -503,6 +535,7 @@ public class DebugTreeBuilderTests
        Assert.Equal("Tank1", tree[1].Key);
    }

+    /// <summary>Verifies that a filter with no matches returns an empty alarm forest.</summary>
    [Fact]
    public void Filter_NoMatches_ReturnsEmptyAlarmForest()
    {
@@ -512,6 +545,7 @@ public class DebugTreeBuilderTests
        Assert.Empty(tree);
    }

+    /// <summary>Verifies that mixed computed and native alarms produce both subtrees.</summary>
    [Fact]
    public void MixedComputedAndNative_ProduceBothSubtrees()
    {
@@ -536,6 +570,7 @@ public class DebugTreeBuilderTests
        Assert.Equal("Tank1.Levels::Tank1.Level.HiHi", Assert.Single(binding.Children).Key);
    }

+    /// <summary>Verifies that empty alarm input returns an empty forest.</summary>
    [Fact]
    public void EmptyAlarmInput_ReturnsEmptyForest()
    {
@@ -543,6 +578,7 @@ public class DebugTreeBuilderTests
        Assert.Empty(tree);
    }

+    /// <summary>Verifies that computed and native alarms sharing a prefix keep distinct binding and leaf nodes.</summary>
    [Fact]
    public void Native_ComputedAndNativeSharePrefix_DistinctBindingAndLeaf()
    {