Skip to content

Fix malformed XML doc comments from BBCode inside code blocks - #49

Open
cobriensr wants to merge 1 commit into
godotengine:masterfrom
cobriensr:fix-doc-xml-codeblock-inline-tags
Open

Fix malformed XML doc comments from BBCode inside code blocks#49
cobriensr wants to merge 1 commit into
godotengine:masterfrom
cobriensr:fix-doc-xml-codeblock-inline-tags

Conversation

@cobriensr

@cobriensr cobriensr commented Jul 18, 2026

Copy link
Copy Markdown

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 as a[i] in shader code is turned into a stray <i> element, producing unbalanced XML.

For example, VisualShaderNodeColorOp's OP_OVERLAY docs contain:

result[i] = 2.0 * base * blend;

which generated result<i> = 2.0 * base * blend; inside <code>, so compiling Godot.Bindings with GenerateDocumentationFile=true fails with errors like:

error CS1570: XML comment has badly formed XML -- 'End tag 'code' does not match the start tag 'i'.'

Fix

  • Hoist the existing code-context guard above both the start-tag and end-tag switches in 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.
  • Reset the code-element state (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:

  • Array subscripts (a[i], result[i]) preserved literally inside [codeblock].
  • Recognized inline tags ([b], [i]) preserved literally inside [codeblock].
  • Inline [code] round-trips BBCode-looking content.
  • [codeblocks] keeps the [csharp] half and drops the [gdscript] half, with subscripts preserved.
  • Prose after a [codeblocks] block is no longer treated as in-code (a trailing [b] renders as <b>).

dotnet test tests/Godot.BindingsGeneration.Tests passes (13 converter tests, including the pre-existing ones).

Scope

This addresses the malformed-XML (CS1570) category only. Other generated-doc issues surfaced by GenerateDocumentationFile=true like ambiguous cref references (CS0419) for overloaded methods are independent and left for separate follow-up.

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
cobriensr force-pushed the fix-doc-xml-codeblock-inline-tags branch from ed6632a to fc2ae08 Compare July 18, 2026 01:44
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