Add JavadocToMarkdownDocComment recipe (JEP 467)

[timtebeek]

Summary

Adds a new OpenRewrite recipe (org.openrewrite.java.migrate.lang.JavadocToMarkdownDocComment) that converts traditional Javadoc comments (/** ... */) to Markdown documentation comments (///) as introduced by JEP 467: Markdown Documentation Comments in Java 23+.

The recipe is guarded by a UsesJavaVersion(23) precondition so it only activates on projects targeting Java 23 or later.

What's converted

HTML tags → Markdown

Javadoc HTML	Markdown equivalent
<pre>...</pre>	Fenced code blocks (triple backticks)
<code>...</code>	Inline backticks
<em>, <i>	_italic_
<strong>, <b>	**bold**
<p>	Blank line (paragraph break)
<ul>/<li>	- unordered list items
<ol>/<li>	1. ordered list items
Unknown/custom tags	Passed through as-is

Inline tags

Tag	Handling
{@code ...}	Converted to backticks
{@link ...}	Converted to [reference]
{@inheritDoc}, {@snippet}, {@docRoot}, {@value}, {@index}, {@summary}	Preserved as-is

Block tags

All standard block tags (@param, @return, @throws/@exception, @see, @since, @author, @deprecated, @version, @hidden) are preserved in the output. Custom block tags are also passed through.

HTML entities

Decodes <, >, &, ", ',  , and @ to their literal characters.

Edge cases handled

• Pre-block nesting: HTML inside <pre> blocks is not converted (preserves code formatting)
• Multi-line {@code}: Converts to fenced code blocks instead of inline backticks
• Indentation preservation: Derives indentation from the original comment position, applies consistently to all /// lines
• Nested classes: Correct indentation even for inner class members
• Consecutive blank lines: Collapsed into a single blank line
• Empty Javadoc comments: Handled gracefully
• Non-Javadoc comments: /* ... */ and // ... are left unchanged

Test plan

18 unit tests covering:

• Single-line and multi-line Javadoc conversion
• Each HTML tag type (<pre>, <code>, <em>, <strong>, <p>, <ul>, <ol>)
• Inline tags ({@code}, {@link}, {@inheritDoc})
• Block tags (@param, @return, @throws, @see, @deprecated, @since)
• HTML entity decoding
• Javadoc on classes, methods, and fields
• Indentation preservation in nested classes
• No-change for regular (non-Javadoc) comments
• Full ./gradlew build passes

References

• JEP 467: Markdown Documentation Comments

[timtebeek]

It's not a requirement for this work, but there's related work in our parser to add coverage there as well

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