Move eight orphaned doc blocks back to their members, and pin the class (#1745)

[erikdarlingdata]

Closes #1745. Audited at f54485ee (dev), fixed and pinned.

The inventory was six. It is eight — and two of the new ones were introduced by the PRs that fixed this exact class.

#1745 listed six sites found on dev before #1744 merged. Re-scanning dev at f54485ee finds eight. The two additions are DarlingWorker.cs and DarlingSelfAlertEvaluator.cs — the two files #1739's alert-surfacing fix touched. So the class recurred inside the change that was fixing two other instances of it, and shipped.

The defect is worse than duplication: it is displacement

The issue framed this as a member carrying two summaries. That undersells it. The mechanism is an edit inserting a new member and its summary above an existing summary rather than below it. The result is two casualties, not one:

• the new member reads with a description of something else entirely, and
• the member the orphaned block actually described is left with no documentation at all.

RunCollectionLoopAsync and EvaluateCompressionJobsAsync are both currently undocumented on dev for exactly this reason.

That inverts the fix. Seven of the eight needed the orphaned block moved back to its real member. Only one was a superseded duplicate safe to delete. The obvious sweep — "remove the extra summary" — would have destroyed real documentation at seven of eight sites. The guard's failure message says so explicitly, so the next person hitting it does not reach for the obvious wrong fix.

Per-site disposition — all eight, including the one that needed nothing moved

#	Site (on dev at f54485ee)	Orphaned block describes	Member left undocumented	Verdict
1	DarlingWorker.cs:582	post-bootstrap store/collection loop	RunCollectionLoopAsync:605	MOVE — introduced by #1739/#1744
2	DarlingSelfAlertEvaluator.cs:1127	isolating compression-job entry point	EvaluateCompressionJobsAsync:1235	MOVE — introduced by #1739/#1744
3	TimescaleSupport.cs:369	query_stats DAILY hierarchical CAGG	CreateQueryStatsDailySql:422	MOVE
4	MainWindow.xaml.cs:768	visible-tab refresh + overlap guard	RefreshVisibleAsync:786	MOVE
5	ViewerDataService.FinOps.Inventory.cs:130	Server Inventory base rows	ServerInventorySql:147	MOVE
6	ThemeParityTests.cs:194	repo-root walk-up	FindRepoRoot:198	MOVE
7	RemoteCollectorService.cs:30	the base collector service class	class RemoteCollectorService:99	MOVE
8	LocalDataService.QueryStore.cs:418	superseded per-query history text	none — same member	DELETE

Site 8 is the only genuine duplicate: both summaries describe GetQueryStoreHistoryAsync, the doc was rewritten from "a specific query" to "ALL plans of a query", and the new text was added below the old instead of replacing it. I confirmed there is no per-plan sibling method and that the preceding method (GetQueryStoreComparisonAsync) kept its own docs, so nothing was displaced here.

Every MOVE was verified the same way before touching it: locate the member the orphaned prose actually describes, confirm that member currently has no doc comment, then move the block to it. No block was deleted on the assumption it was redundant.

The pin

Darling/Darling.Tests/DocCommentHygieneTests.cs — walks every .cs outside bin/obj from the repo root and fails on </summary> immediately followed by <summary>.

Two design points worth the review:

It fails rather than skips when it cannot find the tree. A Skip here would mean the rule silently stops being enforced the day the output layout changes, and nobody would notice — which is the same shape as the defect it guards. If the walk-up breaks, this goes red and gets fixed.

Its failure message tells you not to take the obvious fix, because the obvious fix is wrong seven times out of eight.

Verified in both directions, which is the only thing that makes a pin worth having:

green on the fixed tree                      Passed! - Failed: 0, Passed: 1
stacked block re-introduced in Lite          [FAIL]
                                             Lite\Services\RemoteCollectorService.cs:29
reverted                                     Passed! - Failed: 0, Passed: 1

That red is a mutation in Lite caught by a test living in Darling.Tests, which is the cross-project reach the rule needs.

Coverage limit, stated rather than assumed. CI path filters are per-project, so this runs on any PR tripping the darling or core filter and on every nightly and release build — but a change touching only Lite or Installer will not run it, and would be caught on the next nightly instead. It lives in Darling.Tests because the repo's other source-parsing pins do (HostHeaderGuardTests, DarlingStoreUpgradeTests), which is where someone looks for this kind of guard. The limitation is documented in the test itself.

Testing

dotnet test on all three affected suites: Darling 3360, Lite 1575, Dashboard 768, zero failures.

One disclosure so the number is not overstated: the Lite build emits a pre-existing CS8602 in Lite/MainWindow.AlertEngine.cs:262. That file is not in this diff and the warning is present on dev independently of this change — I am not claiming a zero-warning build, only that this PR adds none.

Net −3 source lines across eight files: seven zero-sum moves plus one deletion. Documentation and one test; no behavior changes anywhere.

🤖 Generated with Claude Code