Add JavadocToMarkdownDocComment recipe (JEP 467)#1019
Merged
Conversation
- Remove redundant hasJavadoc early-return check; ListUtils.flatMap already returns the same list if nothing changes - Extract normalizeLines() and toTextComments() helper methods - Use ListUtils.mapLast() to set the final comment suffix instead of manual index tracking
Member
Author
|
It's not a requirement for this work, but there's related work in our parser to add coverage there as well |
MBoegers
approved these changes
Mar 24, 2026
Contributor
There was a problem hiding this comment.
Reviewed the recipe against JEP 467 and added test coverage + two bug fixes in separate commits on this branch:
Bug fixes:
{@literal}content now wrapped in backticks — previously rendered raw, which breaks Markdown when content contains<T>or similarErroneousnode:getText()returnsList<Javadoc>, was appended directly toStringBuilderproducing garbage output. Changed toconvert(getText())
Test coverage added:
{@literal},{@link ref label},<ol>/<li>,@exception,@implSpec,<i>/<b>,@paramwith{@code},{@docRoot},{@value}, JEP 467hashCode()flagship example- Grouped in
@Nested class Jep467FlagshipExamples - 2 tests marked
@ExpectedToFailfor pre-existing issues (see follow-up comment)
LGTM
Contributor
|
Remaining gaps for full JEP 467 compliance (tracked for follow-up): Bugs found (marked
Missing HTML→Markdown conversions (valid HTML passthrough, but not idiomatic):
Missing test coverage for edge cases:
Good first issues in openrewrite/rewrite-migrate-java ? |
P0 fixes:
- {@literal} content now wrapped in backticks (prevents Markdown
interpretation of special chars like <T>)
- Erroneous node: use convert() instead of append(getText()) which
produced List.toString() garbage
P2 tests for existing code paths:
- {@link ref label} form, ordered lists, @exception, @implSpec,
<i>/<b> tags, @param with inline {@code}, {@docroot}, {@value}
Two tests marked @ExpectedToFail for pre-existing bugs:
- Multi-line {@code}: extra blank lines in fenced code blocks
- @see with qualified names: uses # instead of . for packages
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
2 participants
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
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
<pre>...</pre><code>...</code><em>,<i>_italic_<strong>,<b>**bold**<p><ul>/<li>-unordered list items<ol>/<li>1.ordered list itemsInline tags
{@code ...}{@link ...}[reference]{@inheritDoc},{@snippet},{@docRoot},{@value},{@index},{@summary}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>blocks is not converted (preserves code formatting){@code}: Converts to fenced code blocks instead of inline backticks///lines/* ... */and// ...are left unchangedTest plan
18 unit tests covering:
<pre>,<code>,<em>,<strong>,<p>,<ul>,<ol>){@code},{@link},{@inheritDoc})@param,@return,@throws,@see,@deprecated,@since)./gradlew buildpassesReferences