Markdown in Javadoc comments

Definition

Since Java 23 you can write documentation comments in Markdown by starting each line with /// instead of the old /** ... */ with HTML. Lists, bold, links and code blocks use normal Markdown.

Example code

A documentation comment written in Markdown

/// A shopping cart.
///
/// Features:
/// - adds items
/// - calculates the **total**
///
/// See [Item] for the item type.
class Cart {
    private int total;

    /// Adds an item and returns the new total.
    ///
    /// @param price the price of the item
    /// @return the total after adding it
    int add(int price) {
        total += price;
        return total;
    }
}

record Item(String name) { }

class Demo {
    public static void main(String[] args) {
        Cart cart = new Cart();
        cart.add(100);
        System.out.println(cart.add(50));
    }
}

// Output:
// 150