Add support for Java 23+ triple-slash markdown Javadoc (///)#7087
Merged
jkschneider merged 2 commits intomainfrom Mar 22, 2026
Merged
Add support for Java 23+ triple-slash markdown Javadoc (///)#7087jkschneider merged 2 commits intomainfrom
jkschneider merged 2 commits intomainfrom
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Java 23 (JEP 467) introduced
///triple-slash markdown documentation comments. Previously, the parser treated these as plainTextCommentobjects with no semantic understanding, so recipes likeChangeTypecould not update type references inside{@link}tags.This PR parses
///doc comments into semanticJavadoc.DocCommentAST nodes by detectingJAVADOC_LINEstyle comments from the JDK 25 compiler, handling newDCRawText/EscapeTreeDocTree types, and adding aLineCommentmarker to distinguish///from/** */style for correct round-trip printing.Changes
ReloadableJava25ParserVisitor:formatWithCommentTree()detects///comments viaCommentStyle.JAVADOC_LINE, reconstructs source from multipleTextCommentobjects, and creates aJavadoc.DocCommentwith aLineCommentmarkerReloadableJava25JavadocVisitor: NewinitMarkdown()for///margin handling;visitRawText()andvisitEscape()for new JDK 25 DocTree types;DCRawTexthandling invisitDocCommentandconvertMultiline; bounds check fix invisitTextJavadocPrinter: Prints///(no closing*/) whenLineCommentmarker is presentLineCommentmarker: Distinguishes markdown from traditional doc comment styleJavadocTest.MarkdownDocCommentwith@MinimumJava25covering round-trip, semantic parsing,@param,{@link},ChangeType, and markdown code blocksTest plan
JavadocTest.MarkdownDocCommentTCK tests passrewrite-javamodule tests pass (no regression fromJavadocPrinterchanges)