Markdown documentation comments

suggest change

Since 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 &quot;changes&quot; 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 &lt; 0</code></dd>
</dl>

Note that < didn't need escaping as &lt;. 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:

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&lt;Integer, String&gt;</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:

{@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>&nbsp;in interface&nbsp;<code><a href="Shape.html" title="interface in demo7">Shape</a></code></dd>
<dt>Returns:</dt>
<dd>the area</dd>
</dl>

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.

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>(() -&gt; 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:

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>(() -&gt; 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(() -&gt; "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

Summary

Feedback about page:

Feedback:
Optional: your email if you want me to get back to you:



Table Of Contents