[davidwengier]

Adds @documentation in Razor 12 so components and views can document their generated class without losing source mappings. The XML stays file-local and C# validates it. The first local directive wins, imports cannot suppress it, and bodies containing an unsafe */ aren't emitted. Includes the RZ1047/RZ1048/RZ1049 diagnostics and recovery, declaration-splitting and mapping coverage.

Depends on #85721 (davidwengier/razor-xml-parsing). Part of #85414; editor classification, folding, completion, formatting and quick fixes follow separately.

Review order (five commits): shared directive descriptors; compiler implementation; two baseline-backed examples; remaining test sources and inputs; remaining expected baselines. The fourth commit builds but deliberately lacks the remaining baseline files until the fifth.

Validation: 4,514 compiler tests, 25 VS Code document-diagnostic tests and 47 Visual Studio document-diagnostic tests passed, with analysers enabled and baseline generation off. Both compiler target frameworks and all three affected test projects build. The preparatory slice passed 587 existing syntax/directive checks, and both basic examples passed before adding the rest of the matrix.

Microsoft Reviewers: Open in CodeFlow

[azure-pipelines]

Azure Pipelines:
2 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

Copilot review overview

🔵 Needs a closer look

No concrete defect was found, but the new parser recovery and code-generation behavior warrants final maintainer review.

Review effort: Balanced
Findings: None

What changed in this PR

Adds Razor 12’s @documentation directive, allowing generated component and view classes to receive source-mapped XML documentation safely.

Changes:

• Implements versioned parsing, lowering, code generation, diagnostics, recovery, and import/duplicate handling.
• Adds extensive component, view, source-mapping, compatibility, and cohost diagnostic coverage.
• Documents directive behavior and the RZ1048 warning wave.

File group	Description
docs/​razor/​documentation-directive.md	Documents directive behavior and recovery.
docs/​razor/​warning-levels.md	Documents the RZ1048 warning wave.
DocumentationDirectiveCodeGenerationTest.cs	Component baseline tests.
DocumentationDirectiveCodeGenerationTest_Legacy.cs	Legacy-view baseline tests.
DocumentationDirectiveCompatibilityTest.cs	Version compatibility tests.
DocumentationDirectiveIntegrationTest.cs	Comprehensive compiler behavior tests.
DocumentationDirectiveCodeGenerationTest/​** (89 files)	Component syntax, IR, generated-code, mapping, and diagnostic baselines.
DocumentationDirectiveCodeGenerationTest_Legacy/​** (70 files)	Legacy-view inputs and expected baselines.
DefaultRazorIntermediateNodeLoweringPhase.cs	Lowers documentation syntax to IR.
DefaultRazorMarkupSplitPhase.cs	Retains documentation on declaration partials.
DocumentationDirective.cs	Defines and registers the directive.
DocumentationDirectivePass.cs	Attaches the first local block to the class.
DocumentationIntermediateNode.cs	Safely emits source-mapped XML documentation.
CSharpCodeParser.cs	Parses XML bodies and implements recovery.
ClassifiedSpanVisitor.cs	Classifies the new syntax node.
TagHelperBlockRewriter.cs	Avoids rewriting documentation bodies.
RazorDiagnosticFactory.cs	Defines RZ1047–RZ1049.
RazorProjectEngine.cs	Enables the feature for Razor 12+.
Resources.resx	Adds directive and diagnostic text.
Syntax.xml	Defines the documentation syntax node.
SyntaxKind.cs	Adds its syntax kind.
SyntaxSerializer.cs	Serializes the node in syntax baselines.
Syntax.xml.*.Generated.cs (3 files)	Regenerates syntax nodes, factories, and visitors.
CohostDocumentPullDiagnosticsTest.cs (3 projects)	Verifies endpoint diagnostics across cohost clients.
RazorBaselineIntegrationTestBase.cs	Adds syntax-tree baseline assertions.

[Copilot]

Copilot review overview

🟡 Changes recommended

Razor’s testing guidance must be updated to document the newly exposed syntax-tree baseline support.

Review effort: Balanced
Findings: 1

Open (1)

• Document syntax-tree baselines in Razor testing guidance · New

[jjonescz]

I see you fixed this example to not emit any errors, but other punctuation seems to be still broken. For example, replacing the period with an exclamation mark fails with (4,1): error RZ9981: Unexpected closing tag 'summary' with no matching start tag.

@documentation {<summary>
}
@code { public int Example => 1; }
</summary> Extra information!}
<p>After</p>

Consider adding a test for that too.

[davidwengier]

Great catch! Thank you. Anything that the parser produces a separate token for, and not part of the Text token, would fail and we get bad error recovery.

[davidwengier]

Okay, in order to fix this and not introduce the need to parse XML when recovering from failing to parse XML, I decided to just go with a more relaxed recovery rule. Essentially the documentation parsing might go all the way to EOF, and then recovery will pick a close brace. This is a little extreme, but feels much more pragmatic to me than trying to solve the worlds problems for a document that is ultimately invalid.

[Copilot]

Copilot review overview

🟡 Changes recommended

The new shared syntax-tree baseline capability is not yet reflected in Razor’s living testing guidance, as noted in the unresolved review thread.

Review effort: Balanced
Findings: 1

Open (1)

• Document syntax-tree baselines in Razor testing guidance

[Copilot]

Copilot review overview

🟢 Approval recommended

The parser, lowering, safe emission, mappings, compatibility behavior, and diagnostics are consistently implemented and extensively tested.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Document syntax-tree baselines in Razor testing guidance