Markdown documentation comments
suggest changeSince Java 23 (JEP 467) you can write documentation comments in Markdown. Each line starts with ///, and the text is CommonMark instead of HTML:
/**
* Returns the area, {@code π * r²}.
* <p>
* The result is <em>never</em> negative.
*
* @return the area of this circle
*/
public double area() { ... }
/// Returns the area, `π * r²`.
///
/// The result is _never_ negative.
///
/// @return the area of this circle
public double area() { ... }
Both produce the same javadoc page. The Markdown version has no <p>, no {@code} and no column of * characters to keep aligned.
The feature is final in Java 23 and needs no flags. All the examples below were run with javadoc from JDK 25. The {@snippet} tag, covered at the end, is older (Java 18, JEP 413) and works in both kinds of comment.
The other articles in this chapter describe /** */ comments. The block tags (@param, @return and so on) and the javadoc command line, described in Building Javadocs From the Command Line, work the same way for /// comments.
A first example
package com.example.shapes;
/// A circle with a center point and a radius.
///
/// Circles are **immutable**: every method that "changes" a circle
/// returns a new instance. Use [#scale(double)] to make a bigger one
/// and [#area()] to compute its area.
///
/// Typical use:
///
/// ~~~
/// Circle c = new Circle(0, 0, 2);
/// double a = c.scale(1.5).area();
/// ~~~
///
/// @param x the x coordinate of the center
/// @param y the y coordinate of the center
/// @param radius the radius; must not be negative
/// @author Jane Doe
/// @see Math#PI
/// @since 1.2
public record Circle(double x, double y, double radius) {
/// Creates a circle.
///
/// @throws IllegalArgumentException if `radius < 0`
public Circle {
if (radius < 0) {
throw new IllegalArgumentException("radius < 0");
}
}
/// Returns the area, `π * r²`.
///
/// @return the area of this circle
public double area() {
return Math.PI * radius * radius;
}
/// Returns a circle with the same center and the radius
/// multiplied by `factor`.
///
/// @param factor the scale factor
/// @return a new, scaled circle
public Circle scale(double factor) {
return new Circle(x, y, radius * factor);
}
}
Generate the docs as usual:
javadoc -author -d docs -sourcepath src com.example.shapes
This is the class description in docs/com/example/shapes/Circle.html:
<div class="block"><p>A circle with a center point and a radius.</p>
<p>Circles are <strong>immutable</strong>: every method that "changes" a circle
returns a new instance. Use <a href="#scale(double)"><code>scale(double)</code></a> to make a bigger one
and <a href="#area()"><code>area()</code></a> to compute its area.</p>
<p>Typical use:</p>
<pre><code>Circle c = new Circle(0, 0, 2);
double a = c.scale(1.5).area();
</code></pre>
</div>
<dl class="notes">
<dt>Since:</dt>
<dd>1.2</dd>
<dt>Author:</dt>
<dd>Jane Doe</dd>
<dt>See Also:</dt>
<dd>
<ul class="tag-list">
<li><a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/Math.html#PI" title="class or interface in java.lang" class="external-link"><code>Math.PI</code></a></li>
</ul>
</dd>
</dl>
The constructor's @throws description also went through Markdown, so the backticks became <code>:
<div class="block">Creates a circle.</div>
<dl class="notes">
<dt>Throws:</dt>
<dd><code><a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/IllegalArgumentException.html" title="class or interface in java.lang" class="external-link">IllegalArgumentException</a></code> - if <code>radius < 0</code></dd>
</dl>
Note that < didn't need escaping as <. In Markdown it is written as plain text.
How /// lines are collected
A Markdown doc comment is a run of consecutive lines that each start with ///, placed right before a declaration. Some rules that are easy to miss:
- Any other line ends the comment. That includes a plain
//comment or a line of code. A blank line ends it as well. - Indentation is removed. Javadoc strips the indentation that all the lines have in common after
///. Indentation beyond that counts in Markdown, so 4 extra spaces start an indented code block. - The column of
///doesn't matter, and the lines don't have to line up. ////still counts. A line of four or more slashes is a///line whose text starts with/. A////////banner just above a method becomes its documentation.- Inside a method body,
///is an ordinary comment, just as/** */is.
package demo4;
/**
* A traditional comment with <b>HTML</b>.
* <p>
* Markdown is *not* processed here.
*/
public final class Mixed {
private Mixed() {}
/// Markdown comment on `a()`.
public static void a() {}
/**
* Traditional comment on {@code b()}.
*/
/// Markdown comment on `b()`.
public static void b() {}
/// First run of lines.
// a plain comment
/// Second run of lines.
public static void c() {}
//// Four slashes.
public static void e() {}
}
The generated descriptions, in order (class, a(), b(), c(), e()):
<div class="block">A traditional comment with <b>HTML</b>.
<p>
Markdown is *not* processed here.</div>
<div class="block">Markdown comment on <code>a()</code>.</div>
<div class="block">Markdown comment on <code>b()</code>.</div>
<div class="block">Second run of lines.</div>
<div class="block">/ Four slashes.</div>
/** */ and /// comments can be mixed in one file, even on neighbouring members. Each comment is processed in its own style, so *not* in the class comment stays as literal asterisks.
When two doc comments come before one declaration, the one closest to the declaration is used and the other is ignored. That is how b() and c() lost their first comments. javac -Xlint:dangling-doc-comments (Java 23) warns about such comments:
javac -Xlint:dangling-doc-comments -d classes src/demo4/Mixed.java
src\demo4\Mixed.java:14: warning: [dangling-doc-comments] documentation comment is not attached to any declaration
/**
^
src\demo4\Mixed.java:20: warning: [dangling-doc-comments] documentation comment is not attached to any declaration
/// First run of lines.
^
2 warnings
Here the indentation rules are applied to an indented code block:
/// Indented by three spaces after `///`.
///
/// code: indented four more than the text
///
/// The common indentation is removed first.
public static void a() {}
<div class="block"><p>Indented by three spaces after <code>///</code>.</p>
<pre><code>code: indented four more than the text
</code></pre>
<p>The common indentation is removed first.</p>
</div>
CommonMark in doc comments
Javadoc supports CommonMark and the GitHub-style pipe tables extension. Inline HTML and javadoc's inline tags still work inside it:
package demo11;
/// Helpers for HTTP status codes.
///
/// ## Retry policy
///
/// | Code | Name | Retry? |
/// |-----:|---------------|:------:|
/// | 200 | `OK` | no |
/// | 429 | `TOO_MANY` | yes |
/// | 503 | `UNAVAILABLE` | yes |
///
/// ### Details
///
/// Requests are retried at most {@value #MAX_RETRIES} times
/// (see [#MAX_RETRIES]). Old inline tags work: {@code Map<Integer, String>},
/// {@link String#isBlank()}. So does HTML: H<sub>2</sub>O.
///
/// > Never retry a non-idempotent request such as `POST`
/// > unless the server supports idempotency keys.
///
/// 1. send the request
/// 2. on `429` or `503`, wait and go to step 1
///
/// ---
/// A backslash at the end of a line\
/// forces a line break.
public final class Http {
/// The maximum number of retries.
public static final int MAX_RETRIES = 3;
private Http() {}
}
<div class="block"><p>Helpers for HTTP status codes.</p>
<h3 id="retry-policy-heading">Retry policy</h3>
<table>
<thead>
<tr>
<th align="right">Code</th>
<th>Name</th>
<th align="center">Retry?</th>
</tr>
</thead>
<tbody>
<tr>
<td align="right">200</td>
<td><code>OK</code></td>
<td align="center">no</td>
</tr>
<tr>
<td align="right">429</td>
<td><code>TOO_MANY</code></td>
<td align="center">yes</td>
</tr>
<tr>
<td align="right">503</td>
<td><code>UNAVAILABLE</code></td>
<td align="center">yes</td>
</tr>
</tbody>
</table>
<h4 id="details-heading">Details</h4>
<p>Requests are retried at most <a href="#MAX_RETRIES">3</a> times
(see <a href="#MAX_RETRIES"><code>MAX_RETRIES</code></a>). Old inline tags work: <code>Map<Integer, String></code>,
<a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/String.html#isBlank()" title="class or interface in java.lang" class="external-link"><code>String.isBlank()</code></a>. So does HTML: H<sub>2</sub>O.</p>
<blockquote>
<p>Never retry a non-idempotent request such as <code>POST</code>
unless the server supports idempotency keys.</p>
</blockquote>
<ol>
<li>send the request</li>
<li>on <code>429</code> or <code>503</code>, wait and go to step 1</li>
</ol>
<hr />
<p>A backslash at the end of a line<br />
forces a line break.</p>
</div>
Things to notice:
- Headings are shifted to fit the page they appear on. On a class page
##became<h3>and###became<h4>, because the page already uses<h1>and<h2>. Javadoc also gives each heading anid, so you can link to it. - Tables support column alignment with
:in the separator row. A table can't have a caption, and cells can't span rows or columns. For those, use an HTML<table>, which still works. - Fenced code blocks can use
```or~~~. A language after the opening fence (~~~java) becomesclass="language-java"on the<code>element. Block tags aren't recognized inside a code block, so a line starting with@Overrideor@Testis fine. In a/** */comment such a line had to be written as{@literal @}Test. - Inline tags such as
{@code},{@link},{@value},{@inheritDoc}and{@index}still work. They aren't processed inside code spans or code blocks, where they appear as written. - The first sentence is used as the summary in the member tables, the same as in
/** */comments.
{@inheritDoc} works the same way it does in traditional comments. Markdown in the inherited text is rendered too:
/// A shape.
public interface Shape {
/// Returns the area of this shape, in **square units**.
///
/// The result is never negative.
///
/// @return the area
double area();
}
/// A square.
///
/// @param side the length of a side
public record Square(double side) implements Shape {
/// {@inheritDoc}
///
/// For a square this is `side * side`.
@Override
public double area() {
return side * side;
}
}
<div class="block"><p>Returns the area of this shape, in <strong>square units</strong>.</p>
<p>The result is never negative.</p>
<p>For a square this is <code>side * side</code>.</p>
</div>
<dl class="notes">
<dt>Specified by:</dt>
<dd><code><a href="Shape.html#area()">area</a></code> in interface <code><a href="Shape.html" title="interface in demo7">Shape</a></code></dd>
<dt>Returns:</dt>
<dd>the area</dd>
</dl>
Reference links
In Markdown comments you link to program elements with Markdown reference links, writing the element in square brackets. You don't need {@link}, although it still works:
package demo;
import java.util.List;
/// Examples of reference links.
///
/// - a class: [String]
/// - a fully qualified class: [java.util.Map]
/// - a method: [String#length()]
/// - a method with parameters: [List#of(Object...)]
/// - a field: [Integer#MAX_VALUE]
/// - a member of this class: [#count(String)]
/// - a package: [java.util.concurrent]
/// - a module: [java.net.http/]
/// - custom text: [the length][String#length()]
/// - code-formatted text: [`chars()`][String#chars()]
/// - a web link: [JEP 467](https://openjdk.org/jeps/467)
/// - arrays need escaping: [String#copyValueOf(char\[\])]
public class Links {
/// Counts something in `s`.
///
/// @param s the input
/// @return the count
public static int count(String s) {
return s.length();
}
}
<li>a class: <a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/String.html" title="class or interface in java.lang" class="external-link"><code>String</code></a></li>
<li>a fully qualified class: <a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/Map.html" title="class or interface in java.util" class="external-link"><code>Map</code></a></li>
<li>a method: <a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/String.html#length()" title="class or interface in java.lang" class="external-link"><code>String.length()</code></a></li>
<li>a method with parameters: <a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/List.html#of(E...)" title="class or interface in java.util" class="external-link"><code>List.of(Object...)</code></a></li>
<li>a field: <a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/Integer.html#MAX_VALUE" title="class or interface in java.lang" class="external-link"><code>Integer.MAX_VALUE</code></a></li>
<li>a member of this class: <a href="#count(java.lang.String)"><code>count(String)</code></a></li>
<li>a package: <a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/concurrent/package-summary.html" class="external-link"><code>java.util.concurrent</code></a></li>
<li>a module: <a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.net.http/module-summary.html" class="external-link"><code>java.net.http</code></a></li>
<li>custom text: <a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/String.html#length()" title="class or interface in java.lang" class="external-link">the length</a></li>
<li>code-formatted text: <a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/String.html#chars()" title="class or interface in java.lang" class="external-link"><code>chars()</code></a></li>
<li>a web link: <a href="https://openjdk.org/jeps/467">JEP 467</a></li>
<li>arrays need escaping: <a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/String.html#copyValueOf(char%5B%5D)" title="class or interface in java.lang" class="external-link"><code>String.copyValueOf(char[])</code></a></li>
How the forms map to the old tags:
| Markdown | Traditional equivalent |
|---|---|
[String#length()] |
{@link String#length()} |
[text][String#length()] |
{@linkplain String#length() text} |
[`text`][String#length()] |
{@link String#length() text} |
[text](https://...) |
<a href="https://...">text</a> |
The reference syntax is the same as in {@link}: Class, Class#member, #member for the current class, package and module/. Brackets in an array type must be escaped (char\[\]). Otherwise Markdown treats ] as the end of the link.
Links to JDK classes go to docs.oracle.com, because javadoc links to the platform docs of the --release it runs with. Use -link for other libraries.
Brackets that aren't links
When the text in brackets looks like a Java reference, javadoc treats it as one. An unresolvable reference is an error:
/// Wraps [String#lenght()]. Optional parts are shown as [optional]
/// or, escaped, as \[optional\]. Array indexes like [0] or [i + 1] are fine.
public final class Typo {
private Typo() {}
}
src\demo10\Typo.java:3: error: reference not found
/// Wraps [String#lenght()]. Optional parts are shown as [optional]
^
src\demo10\Typo.java:3: error: reference not found
/// Wraps [String#lenght()]. Optional parts are shown as [optional]
^
2 errors
[optional] is a valid identifier, so javadoc looks for a class named optional. [0] and [i + 1] can't be references and stay as text. Escape brackets that should stay as text with \[ and \], or put the text in a code span. Javadoc still writes the page, with an "invalid reference" box in place of each broken link, but it exits with status 1, which fails Maven and Gradle builds. Typos in links get caught.
Code examples with {@snippet}
{@snippet} (Java 18, JEP 413) is the modern replacement for <pre>{@code ...}</pre>. It works in /** */ comments too, but /// comments suit it better, because nothing inside a /// comment can end it early. In a /** */ comment, a */ in the example code ended the comment:
/// {@snippet :
/// @Test void ok() { /* a comment that would end a classic doc comment */ }
/// }
<pre class="snippet" id="snippet-demo9.Rule1"><code class="language-java">@Test void ok() { /* a comment that would end a classic doc comment */ }
</code></pre>
Compared to a fenced code block, a snippet gets a copy button, a lang attribute (java by default), and markup comments that highlight, replace or link parts of the code. The markup comments don't appear in the output.
Inline snippets
The code goes after the : and runs until the matching }. Curly braces in the code must be balanced. A markup comment at the end of a line applies to that line:
package demo5;
import java.time.Duration;
import java.util.function.Supplier;
/// Runs an action, retrying it when it fails.
///
/// An inline snippet with markup comments:
///
/// {@snippet :
/// Retry retry = Retry.of(3, Duration.ofMillis(100)); // @highlight substring="Retry.of"
/// String body = retry.run(() -> fetch(url)); // @link substring="run" target="#run(Supplier)"
/// System.out.println(body); // @replace regex="body" replacement="..."
/// }
///
/// A whole region can be highlighted, and markup can sit on its own line:
///
/// {@snippet lang=java :
/// // @highlight region type=italic regex="\bretry\b"
/// var retry = Retry.of(5, Duration.ofSeconds(1));
/// retry.run(this::connect);
/// // @end
/// }
public final class Retry {
// ... of(int, Duration) and run(Supplier) ...
}
The generated HTML, with the copy-button markup removed:
<pre class="snippet" id="snippet-demo5.Retry1"><code class="language-java">Retry retry = <span class="bold">Retry.of</span>(3, Duration.ofMillis(100));
String body = retry.<a href="#run(java.util.function.Supplier)"><code>run</code></a>(() -> fetch(url));
System.out.println(...);
</code></pre>
<pre class="snippet" id="snippet-demo5.Retry2"><code class="language-java">var <span class="italic">retry</span> = Retry.of(5, Duration.ofSeconds(1));
<span class="italic">retry</span>.run(this::connect);
</code></pre>
The markup tags:
@highlightwithsubstring="..."orregex="..."(the whole line if neither is given), and an optionaltype=bold|italic|highlighted.@replacewithsubstringorregexplusreplacement. Use it to hide noise, for example to show...in place of a long argument list.@linkwithsubstringorregexplustarget, which takes the same reference syntax as{@link}.- Adding
region(orregion=name) applies a tag to every line up to the matching@end. - A markup comment ending in
:applies to the next line. Use this in languages whose comments can't follow code on the same line.
External snippets
Inline snippets aren't compiled. Code in a separate file can be compiled and tested, so it can't silently go out of date. Javadoc looks for external snippets in a snippet-files directory next to the package's sources:
src/demo6/Retry.java
src/demo6/snippet-files/RetryExample.java
src/demo6/snippet-files/retry.properties
examples/demo6/RetryDemo.java
@start region=name and @end mark the part of the file to show:
import java.time.Duration;
class RetryExample {
void example() {
// @start region="basic"
var retry = Retry.of(3, Duration.ofMillis(100));
String body = retry.run(() -> download("https://example.com")); // @highlight substring="run"
// @end
}
String download(String url) { return ""; }
}
Snippets can be in any language. In a properties file a comment can't follow a value on the same line, so the markup goes on the line before and ends with ::
# @start region="settings"
retry.attempts=3
# @highlight substring="100ms" :
retry.delay=100ms
# @end
class= names a Java class by its fully qualified name. Javadoc looks for it in the directories given with --snippet-path, so the examples can live in a test source tree:
package demo6;
import java.time.Duration;
class RetryDemo {
public static void main(String[] args) {
// @start region="main"
var retry = Retry.of(2, Duration.ZERO);
System.out.println(retry.run(() -> "ok"));
// @end
}
}
The doc comment refers to all three:
/// A retry policy.
///
/// Basic use (from `snippet-files/RetryExample.java`):
///
/// {@snippet file="RetryExample.java" region="basic"}
///
/// Configuration:
///
/// {@snippet file="retry.properties" region="settings"}
///
/// A compiled example found with `--snippet-path`:
///
/// {@snippet class=demo6.RetryDemo region=main}
public final class Retry { ... }
javadoc -d docs -sourcepath src --snippet-path examples demo6
<pre class="snippet" id="snippet-demo6.Retry1"><code class="language-java">var retry = Retry.of(3, Duration.ofMillis(100));
String body = retry.<span class="bold">run</span>(() -> download("https://example.com"));
</code></pre>
<pre class="snippet" id="snippet-demo6.Retry2"><code class="language-properties">retry.attempts=3
retry.delay=<span class="bold">100ms</span>
</code></pre>
<pre class="snippet" id="snippet-demo6.Retry3"><code class="language-java">var retry = Retry.of(2, Duration.ZERO);
System.out.println(retry.run(() -> "ok"));
</code></pre>
The language comes from the file extension. Region markers and markup comments are removed, and the common indentation is stripped. The snippet-files directory isn't copied to the output, and RetryDemo compiles and runs like any other class:
ok
Hybrid snippets
A hybrid snippet names an external file and also includes the code inline. The source stays readable without opening the other file, and javadoc fails if the two differ:
/// {@snippet file="Ex.java" region="hybrid" :
/// var retry = Retry.of(3, Duration.ofMillis(100));
/// String body = retry.run(() -> download("https://example.com"));
/// }
If the inline copy says fetch while the file says download, you get:
src\demo7\Shape.java:11: error: contents mismatch:
/// {@snippet file="Ex.java" region="hybrid" :
^
----------------- inline -------------------
var retry = Retry.of(3, Duration.ofMillis(100));
String body = retry.run(() -> fetch("https://example.com"));
----------------- external -----------------
var retry = Retry.of(3, Duration.ofMillis(100));
String body = retry.run(() -> download("https://example.com"));
1 error
The comparison is strict about whitespace. In tests with JDK 25, a region that starts with a // @start comment on its own line failed to match, because the external side got an extra leading blank line. Putting // @start region="hybrid" at the end of the first line of code fixes it:
var retry = Retry.of(3, Duration.ofMillis(100)); // @start region="hybrid"
String body = retry.run(() -> download("https://example.com"));
// @end
Syntax highlighting
Javadoc in JDK 25 has a --syntax-highlight option. It adds highlight.js to the output and colors the code in snippets and in <pre><code> blocks, including Markdown fenced code blocks:
javadoc --syntax-highlight -d docs -sourcepath src demo5
Tooling and migration
- Which javadoc processes the comments, not which Java version you target. To earlier tools,
///lines are ordinary line comments.javadocfrom JDK 23+ renders them even with--release 17, so a library that supports Java 17 can use Markdown comments as long as its docs are built on a newer JDK. A javadoc older than 23 produces pages without those descriptions. javadoc --disable-line-doc-commentsturns the feature off, so///lines are treated as plain comments again. Use it if a code base has///comments that were never meant as documentation.javac -Xlint:dangling-doc-commentsfinds doc comments that aren't attached to anything, such as a comment separated from its declaration by another comment, or two doc comments on one declaration.- Migrating doesn't have to be all at once.
/** */and///can live side by side, even in one class. When you convert a comment, change{@code x}to`x`,<p>to a blank line,<ul><li>to-lists and{@link X}to[X]. Keep{@link}where you need the link text in code font with custom text, or use[`text`][X]. - Package documentation still goes in
package-info.java(see Package Documentation), and that comment can be a///comment too. Standalone.mddocumentation files aren't supported. HTML files such asoverview.htmlstay HTML.
Summary
///comments (Java 23, JEP 467) are doc comments written in CommonMark, with GitHub-style tables. HTML and inline tags ({@code},{@value},{@inheritDoc}and so on) still work inside them.- A comment is a run of consecutive
///lines before a declaration. Common indentation is removed, any other line ends the comment, and////still counts. - Block tags (
@param,@return,@throws,@see,@since) are the same, and their descriptions are Markdown too. - Link with
[Class#member()],[text][Class#member()]or[text](url). Escape array brackets, and any other brackets that look like a reference, as\[\]. Broken references are errors. - Headings are shifted to fit the page. Code blocks need no escaping of
@,<or*/. {@snippet}(Java 18) adds highlighting, replacements and links through markup comments, and can take code fromsnippet-filesor from--snippet-path, with regions. Hybrid snippets check that the inline copy matches the external file.