Component
Darling Tests
Describe the Bug
DocCommentHygieneTests.NoMemberCarriesTwoStackedSummaryBlocks misses the case where the first <summary> is never CLOSED. It passes on dev today while two members carry stacked summaries, one of which has lost its documentation entirely.
I found this by accident. That pin caught me three times while working #2166, so I wrote a local pre-push version of it — and my first attempt had the same blind spot, keying off /// </summary> and walking forward. It failed its own self-test on a synthetic case, and fixing it to count <summary> OPENINGS inside each contiguous /// run turned up two live instances the CI test does not see.
1. Darling/PerformanceMonitor.Darling.Service/DarlingManagedPostgres.cs ~2368 — a duplicated opening tag on ApplyProcessEnvironment:
/// <summary>
/// <summary>
/// Applies the optional per-invocation environment and working directory shared by both process
/// runners. ...
/// </summary>
private static void ApplyProcessEnvironment(Two openings, one closing. This one is a straightforward stray line to delete — the prose below it clearly belongs to ApplyProcessEnvironment.
2. Lite/Services/QueryStoreSliceRepairService.cs ~576 — the real one, and it is the #1745 displaced-doc pattern the test's own failure message warns about:
/// <summary>
/// Drops DuckDB's cached view of every external file, by toggling the cache off and back on.
///
/// <summary>
/// Promotes a rewritten file over the original, ...
/// </summary>
private async Task PromoteRewrittenFileAsync(That first summary is FlushExternalFileCacheAsync's (declared around line 633), pushed away from its member by an insertion. So PromoteRewrittenFileAsync carries two openings AND FlushExternalFileCacheAsync is left undocumented.
Do not fix #2 by deleting the first block — that would lose real documentation. It needs moving down onto FlushExternalFileCacheAsync.
Expected Behavior
The pin should count <summary> openings within each contiguous run of /// lines, rather than pairing on the closing tag. A contiguous doc run documents exactly one member, so two openings in one run means that member has two summaries — regardless of whether either is closed, and regardless of whether they are written single-line (/// <summary>x</summary>) or spread over several lines.
The mixed form matters and is what fooled my first attempt: the #2166 instance was a single-line summary followed by a multi-line one, which a closing-tag detector cannot see at all.
Actual Behavior
Passes on dev with two stacked blocks present, one of them having orphaned a member's documentation.
Additional Context
Worth noting the pin is genuinely earning its place — it caught three of my own instances in one change set, and every one would have shipped as silently wrong documentation, since XML docs take the LAST block so tooling renders fine and only a human reading the file is misled. This is about widening its net, not doubting it.
Small change: strengthen the assertion, then fix the two it surfaces (one deletion, one move).
Component
Darling Tests
Describe the Bug
DocCommentHygieneTests.NoMemberCarriesTwoStackedSummaryBlocksmisses the case where the first<summary>is never CLOSED. It passes on dev today while two members carry stacked summaries, one of which has lost its documentation entirely.I found this by accident. That pin caught me three times while working #2166, so I wrote a local pre-push version of it — and my first attempt had the same blind spot, keying off
/// </summary>and walking forward. It failed its own self-test on a synthetic case, and fixing it to count<summary>OPENINGS inside each contiguous///run turned up two live instances the CI test does not see.1.
Darling/PerformanceMonitor.Darling.Service/DarlingManagedPostgres.cs~2368 — a duplicated opening tag onApplyProcessEnvironment:Two openings, one closing. This one is a straightforward stray line to delete — the prose below it clearly belongs to
ApplyProcessEnvironment.2.
Lite/Services/QueryStoreSliceRepairService.cs~576 — the real one, and it is the #1745 displaced-doc pattern the test's own failure message warns about:That first summary is
FlushExternalFileCacheAsync's (declared around line 633), pushed away from its member by an insertion. SoPromoteRewrittenFileAsynccarries two openings ANDFlushExternalFileCacheAsyncis left undocumented.Do not fix #2 by deleting the first block — that would lose real documentation. It needs moving down onto
FlushExternalFileCacheAsync.Expected Behavior
The pin should count
<summary>openings within each contiguous run of///lines, rather than pairing on the closing tag. A contiguous doc run documents exactly one member, so two openings in one run means that member has two summaries — regardless of whether either is closed, and regardless of whether they are written single-line (/// <summary>x</summary>) or spread over several lines.The mixed form matters and is what fooled my first attempt: the #2166 instance was a single-line summary followed by a multi-line one, which a closing-tag detector cannot see at all.
Actual Behavior
Passes on dev with two stacked blocks present, one of them having orphaned a member's documentation.
Additional Context
Worth noting the pin is genuinely earning its place — it caught three of my own instances in one change set, and every one would have shipped as silently wrong documentation, since XML docs take the LAST block so tooling renders fine and only a human reading the file is misled. This is about widening its net, not doubting it.
Small change: strengthen the assertion, then fix the two it surfaces (one deletion, one move).