Skip to content

C#: Add documentation comment LST infrastructure#7015

Merged
sambsnyd merged 1 commit intomainfrom
csharp-doc-comments
Mar 31, 2026
Merged

C#: Add documentation comment LST infrastructure#7015
sambsnyd merged 1 commit intomainfrom
csharp-doc-comments

Conversation

@jkschneider
Copy link
Copy Markdown
Member

Summary

  • Adds a structured LST for C# XML documentation comments (///) following the same architectural pattern as Java's Javadoc support
  • CsDocComment interface with 8 node types (vs Javadoc's ~31) using a generic XML model since C# doc comments are XML-native
  • CsDocCommentVisitor with bidirectional CSharpVisitor bridge for cref type references
  • CsDocCommentPrinter and CsDocCommentParser for round-trip fidelity
  • C# side groups consecutive /// lines into a single XmlDocComment in FormatWithComments
  • RPC type mappings between C# XmlDocComment and Java CsDocCommentRawComment

Why not reuse Javadoc?

Javadoc models @param name desc positional syntax with ~31 tag-specific types. C# doc comments are XML (<param name="x">desc</param>) — fundamentally different structure. The architectural pattern is identical (separate tree hierarchy, DocComment implementing Comment, visitor with language visitor bridge via visitSpace()), but the node types are XML-centric.

Architecture

CsDocComment (interface extends Tree)
├── DocComment        — root; implements Comment for Space.comments attachment
├── XmlElement        — <tag>content</tag>
├── XmlEmptyElement   — <tag/>
├── XmlText           — plain text
├── XmlAttribute      — generic attribute
├── XmlCrefAttribute  — cref="Type" with J reference for type attribution
├── XmlNameAttribute  — name="param" with identifier
└── LineBreak         — line break with "/// " margin

Test plan

  • Round-trip tests: parse C# with doc comments, print, verify identical output
  • Visitor traversal tests for all node types
  • Verify cref references get type attribution
  • Edge cases: empty doc comments, nested XML, self-closing tags, multi-line content
  • Run existing C# test suite for no regressions

Add a structured LST for C# XML documentation comments (///) following
the same architectural pattern as Java's Javadoc support: separate tree
hierarchy, visitor with bidirectional CSharpVisitor bridge, and printer.

Java side:
- CsDocComment interface (extends Tree) with 8 node types: DocComment,
  XmlElement, XmlEmptyElement, XmlText, XmlAttribute, XmlCrefAttribute,
  XmlNameAttribute, LineBreak
- CsDocCommentVisitor with bridge to CSharpVisitor for cref references
- CsDocCommentPrinter for serializing back to /// XML format
- CsDocCommentParser for converting raw text to structured tree
- CsDocCommentRawComment for RPC-compatible raw comment transport
- CSharpVisitor.visitSpace() override to detect and process doc comments

C# side:
- XmlDocComment class extending Comment for grouped /// lines
- FormatWithComments groups consecutive /// lines into single XmlDocComment
- CSharpPrinter handles XmlDocComment output
- RPC type mappings for XmlDocComment <-> CsDocCommentRawComment
@github-project-automation github-project-automation bot moved this from In Progress to Ready to Review in OpenRewrite Mar 31, 2026
@sambsnyd sambsnyd merged commit f4e766e into main Mar 31, 2026
1 check passed
@sambsnyd sambsnyd deleted the csharp-doc-comments branch March 31, 2026 19:12
@github-project-automation github-project-automation bot moved this from Ready to Review to Done in OpenRewrite Mar 31, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

2 participants