Skip to content

Add support for Java 23+ triple-slash markdown Javadoc (///)#7087

Merged
jkschneider merged 2 commits intomainfrom
tim/java-23-javadoc-parser
Mar 22, 2026
Merged

Add support for Java 23+ triple-slash markdown Javadoc (///)#7087
jkschneider merged 2 commits intomainfrom
tim/java-23-javadoc-parser

Conversation

@timtebeek
Copy link
Copy Markdown
Member

Summary

Java 23 (JEP 467) introduced /// triple-slash markdown documentation comments. Previously, the parser treated these as plain TextComment objects with no semantic understanding, so recipes like ChangeType could not update type references inside {@link} tags.

This PR parses /// doc comments into semantic Javadoc.DocComment AST nodes by detecting JAVADOC_LINE style comments from the JDK 25 compiler, handling new DCRawText/EscapeTree DocTree types, and adding a LineComment marker to distinguish /// from /** */ style for correct round-trip printing.

Changes

  • ReloadableJava25ParserVisitor: formatWithCommentTree() detects /// comments via CommentStyle.JAVADOC_LINE, reconstructs source from multiple TextComment objects, and creates a Javadoc.DocComment with a LineComment marker
  • ReloadableJava25JavadocVisitor: New initMarkdown() for /// margin handling; visitRawText() and visitEscape() for new JDK 25 DocTree types; DCRawText handling in visitDocComment and convertMultiline; bounds check fix in visitText
  • JavadocPrinter: Prints /// (no closing */) when LineComment marker is present
  • LineComment marker: Distinguishes markdown from traditional doc comment style
  • TCK tests: 9 tests in JavadocTest.MarkdownDocComment with @MinimumJava25 covering round-trip, semantic parsing, @param, {@link}, ChangeType, and markdown code blocks

Test plan

  • All 9 new JavadocTest.MarkdownDocComment TCK tests pass
  • All existing Java 25 unit tests pass
  • Full Java 25 TCK compatibility test suite passes
  • rewrite-java module tests pass (no regression from JavadocPrinter changes)

Parse /// doc comments into semantic Javadoc.DocComment AST nodes,
enabling recipe-based transformations like ChangeType to update
type references inside {@link} tags in markdown documentation.
@timtebeek timtebeek marked this pull request as ready for review March 21, 2026 12:23
@timtebeek timtebeek moved this from In Progress to Ready to Review in OpenRewrite Mar 21, 2026
@jkschneider jkschneider merged commit c5af3e8 into main Mar 22, 2026
1 check passed
@github-project-automation github-project-automation bot moved this from Ready to Review to Done in OpenRewrite Mar 22, 2026
@jkschneider jkschneider deleted the tim/java-23-javadoc-parser branch March 22, 2026 16:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

Archived in project

Development

Successfully merging this pull request may close these issues.

2 participants