Write Docs Like a Human: Markdown + Javadoc in Java 23

Java 23 lets you write documentation comments in Markdown—including headings, lists, links to types/methods, and even simple tables—while still mixing in Javadoc tags when you need them. It’s easier to write, easier to read, and it ships in JDK 23+ via JEP 467.

Why this matters

For decades, Javadoc meant HTML + tags. Powerful, yes—ergonomic, not so much.

Markdown lowers friction for everyone:

Junior devs can contribute sooner (Markdown is familiar).
Senior devs can move faster without wrestling angle brackets.
Diffs get cleaner, because Markdown usually changes fewer characters than HTML.

If your team values readable code, readable docs should be part of the same standard.

The big ideas (at a glance)

Available in Java 23+, delivered as JEP 467.
Write doc comments as adjacent line comments starting with ///.
Uses CommonMark Markdown; supports GFM pipe tables; and you can still use Javadoc tags like @param, @return, @link.
Link to program elements with tidy Markdown: [List], [String#chars()], [java.base/].
Doc files can be Markdown too (in doc-files), and are processed by javadoc.

Quick syntax cheat-sheet

Basic Markdown doc comment + tags

/// # Creates a user
/// Use this to create a *new* user.
///
/// - Validates input
/// - Persists to storage
/// - Returns [Optional]
///
/// @param name the user's display name
/// @return a new [Optional] user
public Optional<User> create(String name) { ... }

Program element links

/// See [java.util.List], [String#chars()], [java.base/]

GFM tables

/// | Status | Code |
/// |--------|------|
/// | OK     | 200  |
/// | Error  | 500  |

Links/tables and the /// style are specified by JEP 467 and the Javadoc guidance for JDK 23+.

How it works (conceptually)

1) `///` turns Markdown into API docs

Java 23 introduces a new documentation comment form:

A doc comment is a run of consecutive lines
Each line begins with ///
The content after /// is treated as Markdown

This keeps docs “close to the code” and readable in diffs.

2) Markdown is the default; tags are still first-class

Markdown is great for readability, but tags still matter for structured semantics:

@param, @return, @throws communicate API contracts.
@implSpec, @apiNote capture important design intent.
You can keep using inline constructs like {@link ...} where appropriate.

The winning move is mixing both: Markdown for humans, tags for tooling.

Migration tips

Start new code in Markdown (///) Let legacy /** ... */ comments evolve gradually. No big-bang rewrite needed.
Keep tags for structure @param, @return, and @implSpec still shine—use them.
Mind code fences Inline Javadoc constructs don’t behave like “live tags” inside backticked code spans/blocks. Treat fenced code as literal.
Proofread the generated docs Markdown accepts almost any text, so malformed formatting won’t always error loudly. Always sanity-check rendered output—especially tables and links.

Tooling & build

You don’t need special flags—just write /// comments and run javadoc as usual on JDK 23+.
IDE support is improving; if rendering/highlighting looks odd, verify your IDE version aligns with JDK 23+ behavior.

When to still use HTML / classic Javadoc

Markdown covers most day-to-day docs, but HTML/classic Javadoc can still be better for:

Complex or accessibility-sensitive tables and layouts
Custom HTML snippets (when you need precision)
Tag-heavy semantics like @implSpec and {@inheritDoc} (you can also mix these into Markdown)

Final thought

JEP 467 doesn’t replace Javadoc—it humanizes it. Start writing docs you don’t dread.