Markdown Documentation Comments in Java

When you leave a note for a friend, you write it the way you would type a message, not in a special office format. For almost thirty years, Java documentation comments had to be written in HTML: <p> for paragraphs, <ul><li> for lists, <code> for code. It worked, but it was tiring to write and hard to read in the source file. Since Java 23, you can write documentation comments in Markdown, the same simple format used in README files and chat apps. In this lesson, you will learn how Markdown doc comments look, which Markdown features they support, and how the javadoc tool turns them into web pages.

What Are Markdown Documentation Comments?

A Markdown documentation comment in Java is a documentation comment written as a group of lines that each start with /// (three slashes), and whose text is written in Markdown instead of HTML. The javadoc tool reads these comments and produces the same kind of HTML pages it always has.

The old style still works, and you can mix both in one project:

Old Style and New Style Side by Side

Let's see the same comment written both ways.

/**
 * Returns the fee to pay for one term.
 * <p>
 * The rules are:
 * <ul>
 *   <li>A late payment adds <b>500</b>.</li>
 *   <li>The base fee can't be negative.</li>
 * </ul>
 *
 * @param baseFee the term fee, in rupees
 * @return the amount to pay
 * @see <a href="#totalFee(int,boolean)">totalFee</a>
 */

/// Returns the fee to pay for one term.
///
/// The rules are:
///
/// - A late payment adds **500**.
/// - The base fee can't be negative.
///
/// @param baseFee the term fee, in rupees
/// @return the amount to pay
/// @see #totalFee(int, boolean)

Explanation: a blank /// line starts a new paragraph, so <p> isn't needed. A list is just lines starting with -. Bold is **500**. The javadoc tags (@param, @return, @see) work exactly as before.

Markdown You Can Use

Linking to Other Code

In the old style you wrote {@link java.util.List}. In Markdown comments you put the name in square brackets, like a Markdown link without a URL:

{@link ...} and other inline tags still work if you prefer them.

A Complete Example

Let's see a small class documented only with Markdown comments. It compiles and runs like any other class, because to the compiler these lines are ordinary // comments.

/// Calculates school fees for one term.
///
/// Fees are in **rupees**. A late payment adds a fixed fine.
/// See [#totalFee(int, boolean)] for the rules.
///
/// | Rule      | Amount |
/// |-----------|--------|
/// | Late fine | 500    |
///
/// @author Navika Anamaneni
public class FeeCalculator {
 
    /// Creates a calculator with the standard rules.
    public FeeCalculator() {
    }
 
    /// Returns the fee to pay for one term.
    ///
    /// - A late payment adds 500.
    /// - The base fee can't be negative.
    ///
    /// @param baseFee the term fee before any fine, in rupees
    /// @param late    `true` if the payment is after the due date
    /// @return the amount to pay
    /// @throws IllegalArgumentException if `baseFee` is negative
    public int totalFee(int baseFee, boolean late) {
        if (baseFee < 0) {
            throw new IllegalArgumentException("baseFee < 0");
        }
        return late ? baseFee + 500 : baseFee;
    }
 
    /// Prints the fee with and without the late fine.
    ///
    /// @param args not used
    public static void main(String[] args) {
        FeeCalculator calc = new FeeCalculator();
        System.out.println(calc.totalFee(15000, false));
        System.out.println(calc.totalFee(15000, true));
    }
}

15000
15500

Now generate the documentation pages:

javadoc -d docs FeeCalculator.java

Loading source file FeeCalculator.java...
Constructing Javadoc information...
Creating destination directory: "docs/"
Building index for all the packages and classes...
Standard Doclet version 25.0.5.0.3
Building tree for all the packages and classes...
Generating docs/FeeCalculator.html...
...
Generating docs/index.html...

Explanation: open docs/FeeCalculator.html in a browser. The class description shows "rupees" in bold, the rules as an HTML table, and the method link as a clickable totalFee(int, boolean). The method's bullet list, parameters, return value and exception appear in their usual places. There are no warnings, because every public element has a comment.

In Practice

• New code: prefer /// comments. They are quicker to write and easier to review in a pull request.
• Existing code: there is no need to convert old comments. Both styles produce the same pages and can live side by side, even in one class.
• Tooling: use JDK 23 or newer for javadoc. An older javadoc treats /// lines as plain comments and ignores them.

Common Mistakes

Forgetting the blank /// line before a list or table. Like normal Markdown, a list right after a sentence may be read as part of the paragraph. Leave an empty /// line first.

Mixing /** and /// on the same element. Use one style per comment. If both are present, only the comment closest to the declaration is used.

Using HTML out of habit. HTML tags still work inside Markdown comments, but they defeat the purpose. Write **bold**, not <b>bold</b>.

Only two slashes. // text is a normal comment and never reaches the documentation. It must be exactly three.

Practice

1. Easy: Add a Markdown comment to a method discountFor(int siblings) that returns 10 percent off for each sibling, with a bullet list of the rules. Run javadoc and open the page.
2. Harder: Take one class from an earlier project that uses /** ... */ comments with <p>, <ul> and {@code ...}, and rewrite its comments in Markdown. Compare the two generated pages.