Fix malformed XML doc comments from BBCode inside code blocks - #49
Open
cobriensr wants to merge 1 commit into
Open
Fix malformed XML doc comments from BBCode inside code blocks#49cobriensr wants to merge 1 commit into
cobriensr wants to merge 1 commit into
Conversation
When converting Godot's BBCode documentation to C# XML doc comments, recognized inline tags ([b], [i], [u], [url], etc.) were emitted as real XML elements even inside a [codeblock]/[csharp] block. Text that merely looks like a tag — most commonly an array subscript such as a[i] in shader code — was turned into a stray <i> element, producing unbalanced XML that fails to compile when GenerateDocumentationFile is enabled (CS1570). While inside a code context, preserve every tag except the code-state tags (codeblock/codeblocks/csharp) as literal text, via a shared TryHandleTagInCodeContext helper used by both the start-tag and end-tag handlers. Also decouple the two code-context state flags so [codeblocks] alone controls inCodeBlocksTag, and inCodeTag (preserve) is always checked before inCodeBlocksTag (ignore). This keeps the generated XML balanced for a top-level [csharp] block, for a [codeblocks] closed while a code block is still open, and for a [codeblock] nested inside [codeblocks]. This addresses the malformed-XML (CS1570) category only; other generated-doc issues such as ambiguous cref references (CS0419) are separate and left for follow-up. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
cobriensr
force-pushed
the
fix-doc-xml-codeblock-inline-tags
branch
from
July 18, 2026 01:44
ed6632a to
fc2ae08
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
When the bindings generator converts Godot's BBCode documentation into C# XML doc comments, recognized inline tags (
[b],[i],[u],[br],[url], …) are emitted as real XML elements even inside a[codeblock]/[csharp]block. Text that merely looks like a tag, most commonly an array subscript such asa[i]in shader code is turned into a stray<i>element, producing unbalanced XML.For example,
VisualShaderNodeColorOp'sOP_OVERLAYdocs contain:which generated
result<i> = 2.0 * base * blend;inside<code>, so compilingGodot.BindingswithGenerateDocumentationFile=truefails with errors like:Fix
XmlDocConverter, so that inside a code context every tag except the ones that manage the code state (codeblock/codeblocks/csharp) is preserved as literal text, matching how unrecognized tags were already handled.inCodeTag) when closing a[csharp]/[codeblocks]block. Previously it was left set, so prose following a[codeblocks]block was treated as if still inside a code block (a latent bug the guard above would otherwise have made visible in trailing prose).Tests
Added to
XmlDocConverterTests:a[i],result[i]) preserved literally inside[codeblock].[b],[i]) preserved literally inside[codeblock].[code]round-trips BBCode-looking content.[codeblocks]keeps the[csharp]half and drops the[gdscript]half, with subscripts preserved.[codeblocks]block is no longer treated as in-code (a trailing[b]renders as<b>).dotnet test tests/Godot.BindingsGeneration.Testspasses (13 converter tests, including the pre-existing ones).Scope
This addresses the malformed-XML (CS1570) category only. Other generated-doc issues surfaced by
GenerateDocumentationFile=truelike ambiguouscrefreferences (CS0419) for overloaded methods are independent and left for separate follow-up.