docs(src): add missing XML docs and strip tracking-ID comments

Sweep of 203 source files resolving CommentChecker findings: add
<summary>/<param>/<returns>/<inheritdoc> where missing, and remove
resolved task/issue tracking markers (Tests-NNN, Worker-NNN, Server-NNN,
Task N) from code comments. Comment/doc-only — no logic changes.
Server+Tests build clean under TreatWarningsAsErrors.
This commit is contained in:
Joseph Doherty
2026-07-07 14:09:49 -04:00
parent 8914472706
commit fca978de07
203 changed files with 1834 additions and 1383 deletions
@@ -14,6 +14,7 @@ public sealed class WorkerFrameProtocolTests
private const string Nonce = "nonce-secret";
/// <summary>Verifies that valid envelopes round-trip through write and read.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task WriteAndReadAsync_WithValidEnvelope_RoundTripsFrame()
{
@@ -32,6 +33,7 @@ public sealed class WorkerFrameProtocolTests
}
/// <summary>Verifies that wrong protocol version throws mismatch error.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ReadAsync_WithWrongProtocolVersion_ThrowsProtocolVersionMismatch()
{
@@ -49,6 +51,7 @@ public sealed class WorkerFrameProtocolTests
}
/// <summary>Verifies that wrong session ID throws mismatch error.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ReadAsync_WithWrongSessionId_ThrowsSessionMismatch()
{
@@ -72,6 +75,7 @@ public sealed class WorkerFrameProtocolTests
/// length prefix is the leading four bytes of the stream, so a four-zero-byte
/// stream is exactly a frame declaring a zero-length payload.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ReadAsync_WithZeroLengthPayload_ThrowsMalformedLength()
{
@@ -93,6 +97,7 @@ public sealed class WorkerFrameProtocolTests
/// A small maximum is configured so the rejection is asserted without
/// allocating a multi-megabyte buffer.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ReadAsync_WithPayloadAboveConfiguredMaximum_ThrowsMessageTooLarge()
{
@@ -115,6 +120,7 @@ public sealed class WorkerFrameProtocolTests
}
/// <summary>Verifies that malformed payload throws invalid envelope error.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ReadAsync_WithMalformedPayload_ThrowsInvalidEnvelope()
{
@@ -130,7 +136,7 @@ public sealed class WorkerFrameProtocolTests
}
/// <summary>
/// Worker.Tests-021 (a): pins the <c>EndOfStream</c> branch of
/// Pins the <c>EndOfStream</c> branch of
/// <c>WorkerFrameReader.ReadExactlyOrThrowAsync</c>. The gateway
/// closing its end of the pipe during a partial-frame read is the
/// most common production transport failure; the reader must
@@ -140,6 +146,7 @@ public sealed class WorkerFrameProtocolTests
/// payload but only supplies 50 bytes, so the inner read loop sees
/// <c>bytesRead == 0</c> mid-frame.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ReadAsync_WhenStreamEndsMidFrame_ThrowsEndOfStream()
{
@@ -157,16 +164,16 @@ public sealed class WorkerFrameProtocolTests
}
/// <summary>
/// Worker.Tests-021 (b): pins the writer-side
/// <c>MessageTooLarge</c> branch. A session that constructs an
/// envelope whose serialised size exceeds <c>MaxMessageBytes</c>
/// must be rejected by the writer before any bytes are sent down
/// the pipe, so a misbehaving producer cannot push the receiver
/// past its bounds. A small <c>MaxMessageBytes</c> is configured
/// so a modest <c>GatewayHello</c> payload — with its nonce
/// padded out to several hundred bytes — exceeds the limit
/// Pins the writer-side <c>MessageTooLarge</c> branch. A session that
/// constructs an envelope whose serialised size exceeds
/// <c>MaxMessageBytes</c> must be rejected by the writer before any
/// bytes are sent down the pipe, so a misbehaving producer cannot
/// push the receiver past its bounds. A small <c>MaxMessageBytes</c>
/// is configured so a modest <c>GatewayHello</c> payload — with its
/// nonce padded out to several hundred bytes — exceeds the limit
/// without allocating anything large.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task WriteAsync_WithEnvelopeAboveConfiguredMaximum_ThrowsMessageTooLarge()
{
@@ -191,11 +198,10 @@ public sealed class WorkerFrameProtocolTests
}
/// <summary>
/// Worker.Tests-021 (c): documents that the writer-side
/// <c>InvalidEnvelope</c> branch (raised when
/// <c>WorkerEnvelope.CalculateSize()</c> returns 0) is unreachable
/// through public API. <c>WorkerEnvelopeValidator.Validate</c> (run
/// before the size check in <c>WorkerFrameWriter.WriteAsync</c>)
/// Documents that the writer-side <c>InvalidEnvelope</c> branch
/// (raised when <c>WorkerEnvelope.CalculateSize()</c> returns 0) is
/// unreachable through public API. <c>WorkerEnvelopeValidator.Validate</c>
/// (run before the size check in <c>WorkerFrameWriter.WriteAsync</c>)
/// rejects any envelope whose <c>BodyCase</c> is <c>None</c> with
/// <c>InvalidEnvelope</c>; a body-less envelope is therefore
/// intercepted before the empty-payload branch can fire. Any
@@ -209,6 +215,7 @@ public sealed class WorkerFrameProtocolTests
/// would weaken the writer against future serialisation
/// regressions; this test makes its rationale visible.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task WriteAsync_WithEmptyEnvelope_ThrowsInvalidEnvelopeFromValidator()
{
@@ -233,6 +240,7 @@ public sealed class WorkerFrameProtocolTests
}
/// <summary>Verifies that concurrent writes produce complete serialized frames.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task WriteAsync_WithConcurrentCalls_SerializesCompleteFrames()
{
@@ -256,12 +264,13 @@ public sealed class WorkerFrameProtocolTests
}
/// <summary>
/// Worker-009 regression: the reader rents its payload buffer from a
/// shared pool, so a rented buffer can be larger than the current frame
/// and may carry bytes from a previous, larger frame. Reading frames of
/// differing sizes back-to-back through one reader must parse each frame
/// using only its own payload length, never trailing pooled bytes.
/// The reader rents its payload buffer from a shared pool, so a rented
/// buffer can be larger than the current frame and may carry bytes from
/// a previous, larger frame. Reading frames of differing sizes
/// back-to-back through one reader must parse each frame using only its
/// own payload length, never trailing pooled bytes.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ReadAsync_WithVaryingFrameSizes_ParsesEachFrameExactly()
{