Skip to content

Escape the angle-bracket placeholders introduced into two XML doc comments - #3025

Merged
erikdarlingdata merged 2 commits into
devfrom
fix/escape-doc-comment-placeholders
Sep 5, 2026
Merged

erikdarlingdata merged 2 commits into
devfrom
fix/escape-doc-comment-placeholders

Conversation

@erikdarlingdata

Copy link
Copy Markdown
Owner

#3020 replaced a host name with the <host> placeholder in two /// XML doc comments without escaping the angle brackets. Inside doc XML, <host> is an opening tag with no close — not literal text — so the parser sees an unclosed host element and the placeholder is silently swallowed.

Both now use the escaping convention already in this codebase: &lt;host&gt;, matching PgSessionStatesCollector.cs's &lt;insufficient privilege&gt; and the &gt; escape already present a few lines above the first site.

file was now
QueryStoreOpenIntervalState.cs:68 <c><host></c> <c>&lt;host&gt;</c>
PlanCorrectionCollector.cs:151 <host>/<database> &lt;host&gt;/&lt;database&gt;

The third site from #3020 is deliberately left unescaped. Lite.Tests/PlanCorrectionCollectorDefinitionTests.cs:190 sits inside a /* ... */ block comment, not a /// doc comment, so <host>/<database> there is literal text already and escaping it would render the entities visibly. Verified by reading the surrounding block rather than assuming the file's style is uniform.

Why CI did not catch this, which is the part worth keeping

GenerateDocumentationFile is not enabled for these projects, so malformed doc XML is not a build error. #3020 went green on all seven checks — including a full 598s build that really did compile — with both sites broken. The failure is invisible today and shows up as broken IDE tooltips, or as a swallowed placeholder if doc generation is ever turned on.

So there is no guard for this class, and this PR does not add one. Adding GenerateDocumentationFile across these projects would surface every pre-existing doc-XML defect in the tree at once, which is a much larger change than the two lines here and should be its own decision rather than a side effect of fixing them.

@claude

claude Bot commented Sep 5, 2026

Copy link
Copy Markdown

Reviewed. Verified both fix sites: PlanCorrectionCollector.cs:151 and QueryStoreOpenIntervalState.cs:68 are inside /// XML doc comments, where an unescaped <host>/<database> is parsed as an unclosed tag and silently dropped — the &lt;/&gt; escaping matches the existing convention (e.g. PgSessionStatesCollector.cs's &lt;insufficient privilege&gt;). Confirmed the third occurrence (Lite.Tests/PlanCorrectionCollectorDefinitionTests.cs:190) is correctly left unescaped, since it sits inside a /* */ block comment where the angle brackets are already literal text, not doc XML.

No behavioral change, no Lite/Darling parity impact (no SQL, no app logic touched), no security concerns. LGTM.

@erikdarlingdata
erikdarlingdata merged commit ecdea81 into dev Sep 5, 2026
7 checks passed
@erikdarlingdata
erikdarlingdata deleted the fix/escape-doc-comment-placeholders branch September 5, 2026 14:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant