Markdown in Javadoc comments
Write Javadoc comments in Markdown instead of HTML for better readability.
Code Comparison
✕ Java 8
/**
* Returns the {@code User} with
* the given ID.
*
* <p>Example:
* <pre>{@code
* var user = findUser(123);
* }</pre>
*
* @param id the user ID
* @return the user
*/
public User findUser(int id) { ... }
✓ Java 23+
/// Returns the `User` with
/// the given ID.
///
/// Example:
/// ```java
/// var user = findUser(123);
/// ```
///
/// @param id the user ID
/// @return the user
public User findUser(int id) { ... }
Why the modern way wins
Natural syntax
Use backticks for inline code and ``` for blocks instead of HTML tags.
Easier to write
No need for {@code}, <pre>, <p> tags — just write Markdown.
Better in editors
Markdown renders beautifully in modern IDEs and text editors.
Old Approach
HTML-based Javadoc
Modern Approach
Markdown Javadoc
Since JDK
23
Difficulty
beginner
JDK Support
Markdown in Javadoc comments
Available
Available since JDK 23 (Sept 2024)
How it works
Java 23 introduces /// Markdown-style Javadoc comments as an alternative to the traditional /** */ HTML-based format. Markdown syntax is more natural to write and read, with support for code blocks, emphasis, lists, and links. The compiler converts Markdown to HTML for javadoc output.
Related Documentation