docs: strip task-tracking IDs from code comments and fill missing XML docs
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 1m16s
ci / java (push) Successful in 2m5s
ci / portable (push) Failing after 5m9s

Tracking IDs are review bookkeeping that rots in shipped source; the rationale they tagged is kept. Comment-only change (CommentChecker 458 -> 16 false positives).
This commit is contained in:
Joseph Doherty
2026-10-07 15:34:32 -04:00
parent f2e0861709
commit f40409a688
115 changed files with 549 additions and 411 deletions
@@ -521,7 +521,7 @@ public sealed class WorkerFrameProtocolTests
/// Control-frame completion decoupling. The boundary flush is charged per class run, not per
/// control frame: a pass carrying nothing but control frames still pays exactly one flush. Flushing
/// after every control frame
/// would reinstate the syscall-per-heartbeat cost WRK-12 removed.
/// would reinstate the syscall-per-heartbeat cost the earlier per-frame flush design incurred.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
@@ -592,7 +592,7 @@ public sealed class WorkerFrameProtocolTests
}
/// <summary>
/// Verifies a per-frame rejection does not burn a sequence number (WRK-23). The sequence is a
/// Verifies a per-frame rejection does not burn a sequence number. The sequence is a
/// diagnostic counter, so a gap breaks nothing functionally — but an operator correlating a pipe
/// capture reads a gap as a lost frame and chases a bug that does not exist, and the gap-free
/// guarantee the concurrent-write test asserts would otherwise only hold until the first
@@ -664,7 +664,7 @@ public sealed class WorkerFrameProtocolTests
/// <summary>
/// Verifies a negotiated frame maximum below the worker floor is rejected as
/// <c>InvalidConfiguration</c> (WRK-24), and that exactly the floor is adopted. The floor matches
/// <c>InvalidConfiguration</c> and that exactly the floor is adopted. The floor matches
/// the gateway's own <c>GatewayOptionsValidator.MinimumMaxMessageBytes</c>, so the worker never
/// rejects a value the gateway's validator accepts, yet a nonsensical tiny value faults at the
/// handshake instead of leaving a session that fails every later frame.
@@ -684,7 +684,7 @@ public sealed class WorkerFrameProtocolTests
}
/// <summary>
/// WRK-22 / IPC-26. A <c>WriteAsync</c> cancelled while it waits for the write lock must never
/// A <c>WriteAsync</c> cancelled while it waits for the write lock must never
/// have its frame written by the next lock-holder. Writer A holds the lock mid-write (blocked in
/// the stream); an event write is queued and then cancelled; when A is released and a later
/// control frame drains, the wire carries A's frame and the control frame only — the cancelled
@@ -727,7 +727,7 @@ public sealed class WorkerFrameProtocolTests
}
/// <summary>
/// NEXT-04. A frame claimed by the draining lock-holder before its caller's cancellation lands
/// A frame claimed by the draining lock-holder before its caller's cancellation lands
/// is abandoned — the cancelled caller never awaits its completion. If the wire write then
/// faults, the tombstone path's fault-observing continuation must still observe the exception
/// so it never surfaces as <see cref="TaskScheduler.UnobservedTaskException"/>.
@@ -791,7 +791,7 @@ public sealed class WorkerFrameProtocolTests
}
/// <summary>
/// WRK-22 / IPC-26, the review's shutdown scenario. A cancelled event frame queued before a
/// Shutdown scenario: a cancelled event frame queued before a
/// shutdown-ack control frame must not trail the ack on the wire: the tombstone rule plus the
/// control-before-event scheduler keeps the ack the last frame written.
/// </summary>
@@ -830,9 +830,9 @@ public sealed class WorkerFrameProtocolTests
}
/// <summary>
/// WRK-25. The batch entry point enqueues a whole event burst under one lock acquisition and
/// The batch entry point enqueues a whole event burst under one lock acquisition and
/// drains it together, so N events cost exactly one flush and reach the wire in batch order with
/// monotonic sequences — the coalescing WRK-12 shipped, now on the event hot path.
/// monotonic sequences — the flush coalescing now on the event hot path.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
@@ -868,7 +868,7 @@ public sealed class WorkerFrameProtocolTests
}
/// <summary>
/// WRK-25. Control-before-event still holds mid-batch: a control frame queued while a batch is
/// Control-before-event still holds mid-batch: a control frame queued while a batch is
/// draining jumps ahead of the batch's remaining events.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
@@ -1223,7 +1223,7 @@ public sealed class WorkerFrameProtocolTests
// A MemoryStream whose first write blocks until released and whose second write blocks until
// released and then throws, so a test can abandon a claimed frame by cancellation and fault its
// wire write afterwards (NEXT-04).
// wire write afterwards.
private sealed class SecondWriteFaultingGatedStream : MemoryStream
{
private readonly SemaphoreSlim _firstRelease = new SemaphoreSlim(0);
@@ -1235,6 +1235,8 @@ public sealed class WorkerFrameProtocolTests
private readonly string _faultMessage;
private int _writeCount;
/// <summary>Initializes a new instance of the <see cref="SecondWriteFaultingGatedStream"/> class.</summary>
/// <param name="faultMessage">The message of the exception thrown by the second write.</param>
public SecondWriteFaultingGatedStream(string faultMessage)
{
_faultMessage = faultMessage;
@@ -20,7 +20,7 @@ public sealed class WorkerPipeSessionTests
private const string SessionId = "session-1";
private const string Nonce = "nonce-secret";
// Byte-heavy drain fixture (WRK-21). 10,000 events at ~1.7 KiB each is ~17 MB of queue — far
// Byte-heavy drain fixture. 10,000 events at ~1.7 KiB each is ~17 MB of queue — far
// more than one frame — so DrainEvents must truncate.
//
// Two limits below are harness accommodations, not properties of the fix. PipePair runs both
@@ -559,7 +559,7 @@ public sealed class WorkerPipeSessionTests
}
/// <summary>
/// The WRK-21 repro. A queue full of byte-heavy events (large string values — the payload
/// The repro for the oversized drain reply. A queue full of byte-heavy events (large string values — the payload
/// profile this gateway exists for) used to make <c>DrainEvents max_events = 0</c> build a
/// reply above the negotiated frame maximum: the writer rejected the frame, the exception
/// unwound the session, and the already-dequeued events were gone. The drain is now
@@ -703,7 +703,7 @@ public sealed class WorkerPipeSessionTests
{
// The lowest Worker.MaxMessageBytes GatewayOptionsValidator permits: the public gRPC floor
// (1024) plus the 64 KiB envelope-overhead reserve. The naive budget — frame max less the
// two reserves the DrainEvents budget subtracts (IPC-33) — would be negative here; the
// two reserves the DrainEvents budget subtracts — would be negative here; the
// floored budget is half of the frame max (~33 KiB).
const uint validatorFloorFrameMax = 1024 + (64 * 1024);
using CancellationTokenSource cancellation = new(TimeSpan.FromSeconds(60));
@@ -761,7 +761,7 @@ public sealed class WorkerPipeSessionTests
}
/// <summary>
/// Verifies the control-reply write seam is not session-fatal on size (WRK-21 backstop). The
/// Verifies the control-reply write seam is not session-fatal on size (the drain backstop). The
/// reply builders size their payloads, so this path needs a deliberately budget-blind drain
/// to reach — but that is the point: a future command or a sizing bug must degrade to an
/// error reply for that correlation, never to a dead session.
@@ -859,7 +859,7 @@ public sealed class WorkerPipeSessionTests
}
/// <summary>
/// IPC-30. An event above the negotiated frame maximum is undeliverable end to end (the pipe
/// An event above the negotiated frame maximum is undeliverable end to end (the pipe
/// maximum sits only an envelope reserve above the public gRPC cap), so the session stays
/// fatal by design — but the death must be structured: a WorkerFault naming the event, with
/// no value payload in it, before the process exits. Silently dropping the event or
@@ -915,7 +915,7 @@ public sealed class WorkerPipeSessionTests
}
/// <summary>
/// WRK-31, the other side of the invariant. The graceful path leaves the message loop
/// The other side of the transport-ownership invariant. The graceful path leaves the message loop
/// through its <c>return</c> after the shutdown ack, with that iteration's read already
/// awaited — so there is no abandoned read for teardown to account for. Pinning this keeps
/// the new disposal-and-observe step a pure no-op on the path production takes every time a
@@ -955,7 +955,7 @@ public sealed class WorkerPipeSessionTests
}
/// <summary>
/// WRK-31. The session now owns and closes the transport rather than leaving it to
/// The session now owns and closes the transport rather than leaving it to
/// <c>WorkerPipeClient</c>'s <c>using</c>, because the read it unblocks has to be observed
/// while the session still holds it. This asserts the closure actually happens on the
/// session's own timeline: the gateway end of the pipe must see disconnection while
@@ -1250,7 +1250,7 @@ public sealed class WorkerPipeSessionTests
}
/// <summary>
/// WRK-27. An STA call outside the command dispatcher (the alarm poll) advertises itself on
/// An STA call outside the command dispatcher (the alarm poll) advertises itself on
/// the heartbeat snapshot's <c>StaCallInProgress</c> flag, and the watchdog grants it the same
/// grace-to-ceiling suppression as a dispatched command: stale STA activity within the ceiling
/// does not fault while the flag is set, but stale activity beyond the ceiling faults anyway.
@@ -1340,8 +1340,8 @@ public sealed class WorkerPipeSessionTests
}
/// <summary>
/// WRK-25. The event drain loop submits a whole drained batch through the writer's batch entry
/// point, so a burst of 128 events costs one flush, not 128 — the assertion the WRK-12
/// The event drain loop submits a whole drained batch through the writer's batch entry
/// point, so a burst of 128 events costs one flush, not 128 — the assertion the
/// tracking claim needed to actually hold on the event hot path.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
@@ -1413,7 +1413,7 @@ public sealed class WorkerPipeSessionTests
}
/// <summary>
/// WRK-24. A GatewayHello negotiating a frame maximum below the worker floor faults at the
/// A GatewayHello negotiating a frame maximum below the worker floor faults at the
/// handshake with a fault frame rather than being adopted — mirroring the above-ceiling
/// handshake behavior — so a nonsensical tiny value never leaves a session that fails every
/// later frame. No message loop is entered.
@@ -2338,7 +2338,7 @@ public sealed class WorkerPipeSessionTests
public sealed class AbandonedPipeReadTeardownTests
{
/// <summary>
/// WRK-31. A fault exit unwinds the message loop while its frame read is still pending,
/// A fault exit unwinds the message loop while its frame read is still pending,
/// and on net48 nothing can cancel that read — <c>NamedPipeClientStream.ReadAsync</c>
/// ignores the token, so only closing the handle ends it. The session must therefore
/// dispose the transport itself and account for the read that disposal unblocks: the