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
@@ -20,6 +20,8 @@ public class StandbyRequestForwardingTests
    // Filter: when does a standby relay, and when does it refuse?
    // ------------------------------------------------------------------

+    /// <summary>Verifies that the relay does not negotiate an encoding it cannot forward.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Relay_DoesNotNegotiateAnEncodingItCannotForward()
    {
@@ -34,6 +36,9 @@ public class StandbyRequestForwardingTests

    }

+    /// <summary>Verifies that a request the peer applied whose response was lost is not replayed.</summary>
+    /// <param name="timeout">True to simulate the lost response as a timeout, false to simulate a connection failure.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Theory]
    [InlineData(false)]
    [InlineData(true)]
@@ -56,6 +61,8 @@ public class StandbyRequestForwardingTests
        Assert.Contains("OUTCOME_UNKNOWN", await new StreamReader(ctx.Response.Body).ReadToEndAsync());
    }

+    /// <summary>Verifies that a standby with a forwarder configured relays the request and does not run the handler.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Standby_WithForwarderConfigured_RelaysAndDoesNotRunHandler()
    {
@@ -71,6 +78,8 @@ public class StandbyRequestForwardingTests
        Assert.True(ctx.Items.ContainsKey(InboundApiEndpointFilter.RelayedToActiveItemKey));
    }

+    /// <summary>Verifies that a standby without a configured forwarder returns 503 STANDBY_NODE marked for peers.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Standby_WithForwarderUnconfigured_Returns503StandbyNode_MarkedForPeers()
    {
@@ -87,6 +96,8 @@ public class StandbyRequestForwardingTests
        Assert.False(ctx.Items.ContainsKey(InboundApiEndpointFilter.RelayedToActiveItemKey));
    }

+    /// <summary>Verifies that a standby does not relay an already forwarded request again (loop guard).</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Standby_AlreadyForwardedRequest_IsNotRelayedAgain_LoopGuard()
    {
@@ -103,6 +114,8 @@ public class StandbyRequestForwardingTests
        Assert.Equal("1", ctx.Response.Headers[HttpStandbyRequestForwarder.StandbyResponseHeader]);
    }

+    /// <summary>Verifies that a standby returns 413 for an oversized body before relaying.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Standby_OversizedBody_Returns413_BeforeRelaying()
    {
@@ -119,6 +132,8 @@ public class StandbyRequestForwardingTests
        AssertStatus(result, StatusCodes.Status413PayloadTooLarge);
    }

+    /// <summary>Verifies that an active node serves a forwarded request locally.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task ActiveNode_ForwardedRequest_IsServedLocally()
    {
@@ -139,6 +154,8 @@ public class StandbyRequestForwardingTests
    // Forwarder: relay mechanics against a fake HTTP peer
    // ------------------------------------------------------------------

+    /// <summary>Verifies that the forwarder relays the method, path, query, headers and body and replays the peer response.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Forwarder_RelaysMethodPathQueryHeadersAndBody_AndReplaysPeerResponse()
    {
@@ -175,6 +192,8 @@ public class StandbyRequestForwardingTests
        Assert.Equal("application/json", seen.Content!.Headers.ContentType!.MediaType);
    }

+    /// <summary>Verifies that the forwarder replays a peer error status unchanged.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Forwarder_ReplaysPeerErrorStatusUnchanged()
    {
@@ -191,6 +210,8 @@ public class StandbyRequestForwardingTests
        Assert.Contains("NOT_APPROVED", Encoding.UTF8.GetString(relayed.Body));
    }

+    /// <summary>Verifies that the forwarder tries the next peer with the same body when a peer is unreachable.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Forwarder_PeerUnreachable_TriesNextPeer_WithSameBody()
    {
@@ -211,6 +232,8 @@ public class StandbyRequestForwardingTests
        Assert.Equal(new[] { "{\"n\":7}", "{\"n\":7}" }, bodies);
    }

+    /// <summary>Verifies that the forwarder tries the next peer when a peer is also a standby.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Forwarder_PeerIsAlsoStandby_TriesNextPeer()
    {
@@ -233,6 +256,8 @@ public class StandbyRequestForwardingTests
        Assert.Equal("served", Encoding.UTF8.GetString(relayed.Body));
    }

+    /// <summary>Verifies that a genuine 503 from the active peer is replayed rather than retried.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Forwarder_Genuine503FromActivePeer_IsReplayed_NotRetried()
    {
@@ -257,6 +282,8 @@ public class StandbyRequestForwardingTests
        Assert.Equal(1, calls);
    }

+    /// <summary>Verifies that the forwarder returns 503 ACTIVE_NODE_UNREACHABLE when all peers fail.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Forwarder_AllPeersFail_Returns503ActiveNodeUnreachable()
    {
@@ -269,6 +296,8 @@ public class StandbyRequestForwardingTests
        AssertStatus(result, StatusCodes.Status503ServiceUnavailable);
    }

+    /// <summary>Verifies that a peer timeout returns an uncertain result without trying the next peer.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Forwarder_PeerTimesOut_ReturnsUncertainWithoutTryingNextPeer()
    {
@@ -288,6 +317,8 @@ public class StandbyRequestForwardingTests
        AssertStatus(result, StatusCodes.Status502BadGateway);
    }

+    /// <summary>Verifies that a caller abort propagates and does not try the next peer.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Forwarder_CallerAborts_Propagates_DoesNotTryNextPeer()
    {
@@ -307,6 +338,7 @@ public class StandbyRequestForwardingTests
        Assert.Equal(1, calls);
    }

+    /// <summary>Verifies that IsConfigured tracks the peer list.</summary>
    [Fact]
    public void Forwarder_IsConfigured_TracksPeerList()
    {
@@ -314,6 +346,8 @@ public class StandbyRequestForwardingTests
        Assert.True(CreateForwarder(new FakeHandler(_ => throw new InvalidOperationException()), "http://b:5000").IsConfigured);
    }

+    /// <summary>Verifies that a relayed result writes the status, content type and body.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RelayedResult_WritesStatusContentTypeAndBody()
    {
@@ -392,10 +426,17 @@ public class StandbyRequestForwardingTests

    private sealed class StubForwarder : IStandbyRequestForwarder
    {
+        /// <summary>Initializes the stub with its configured flag and canned result.</summary>
+        /// <param name="configured">Whether the forwarder reports itself as configured.</param>
+        /// <param name="result">The result returned from forwarding.</param>
        public StubForwarder(bool configured, IResult result) { IsConfigured = configured; Result = result; }
+        /// <inheritdoc />
        public bool IsConfigured { get; }
+        /// <summary>Gets the canned result returned from forwarding.</summary>
        public IResult Result { get; }
+        /// <summary>Gets the number of times forwarding was invoked.</summary>
        public int Calls { get; private set; }
+        /// <inheritdoc />
        public Task<IResult> ForwardAsync(HttpContext context, CancellationToken cancellationToken)
        {
            Calls++;
@@ -405,15 +446,23 @@ public class StandbyRequestForwardingTests

    private sealed class StubActiveNodeGate : IActiveNodeGate
    {
+        /// <summary>Initializes the gate with a fixed active-node answer.</summary>
+        /// <param name="isActive">Whether this node reports itself as active.</param>
        public StubActiveNodeGate(bool isActive) => IsActiveNode = isActive;
+        /// <inheritdoc />
        public bool IsActiveNode { get; }
    }

    private sealed class FakeHandler : HttpMessageHandler
    {
        private readonly Func<HttpRequestMessage, CancellationToken, Task<HttpResponseMessage>> _send;
+        /// <summary>Initializes the handler with a send delegate that ignores the cancellation token.</summary>
+        /// <param name="send">The delegate that produces the response for a request.</param>
        public FakeHandler(Func<HttpRequestMessage, Task<HttpResponseMessage>> send) => _send = (r, _) => send(r);
+        /// <summary>Initializes the handler with a send delegate that observes the cancellation token.</summary>
+        /// <param name="send">The delegate that produces the response for a request.</param>
        public FakeHandler(Func<HttpRequestMessage, CancellationToken, Task<HttpResponseMessage>> send) => _send = send;
+        /// <inheritdoc />
        protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken ct) =>
            _send(request, ct);
    }
@@ -421,16 +470,30 @@ public class StandbyRequestForwardingTests
    private sealed class FakeHttpClientFactory : IHttpClientFactory
    {
        private readonly HttpMessageHandler _handler;
+        /// <summary>Initializes the factory with the handler every client will use.</summary>
+        /// <param name="handler">The message handler shared by created clients.</param>
        public FakeHttpClientFactory(HttpMessageHandler handler) => _handler = handler;
+        /// <summary>Returns a client over the canned handler.</summary>
+        /// <param name="name">The requested client name (ignored).</param>
+        /// <returns>An <see cref="HttpClient"/> that uses the fake handler.</returns>
        public HttpClient CreateClient(string name) =>
            new(_handler, disposeHandler: false) { Timeout = Timeout.InfiniteTimeSpan };
    }

    private sealed class StaticOptionsMonitor<T> : IOptionsMonitor<T>
    {
+        /// <summary>Initializes the monitor with a fixed value.</summary>
+        /// <param name="value">The value returned by the monitor.</param>
        public StaticOptionsMonitor(T value) => CurrentValue = value;
+        /// <summary>Gets the canned options value.</summary>
        public T CurrentValue { get; }
+        /// <summary>Returns the canned options value regardless of name.</summary>
+        /// <param name="name">The requested options name (ignored).</param>
+        /// <returns>The canned options value.</returns>
        public T Get(string? name) => CurrentValue;
+        /// <summary>Ignores the change listener; the fake never raises changes.</summary>
+        /// <param name="listener">The change listener (ignored).</param>
+        /// <returns>Always null.</returns>
        public IDisposable? OnChange(Action<T, string?> listener) => null;
    }
 }