Skip to content

C#: Add documentation comment LST infrastructure#7015

Open
jkschneider wants to merge 1 commit intomainfrom
csharp-doc-comments
Open

C#: Add documentation comment LST infrastructure#7015
jkschneider wants to merge 1 commit intomainfrom
csharp-doc-comments

Conversation

@jkschneider
Copy link
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: In Progress

Development

Successfully merging this pull request may close these issues.

1 participant