Markdown documentation comments

Key points

• Classic Javadoc is HTML: <p>, <ul>, <li> and entity escapes everywhere.
• JEP 467 adds a Markdown form using /// on each line instead of /** ... */.
• Inside it you write normal Markdown - lists, tables, fenced code, links.
• Javadoc tags still work, and a link becomes [Optional] style instead of an inline tag.
• This one is final in 23, not a preview, so it is safe to adopt once you are on 23+.

Example

// Java 23 (JEP 467). The /// form is not valid Javadoc on Java 21.
//
//   /// Returns the total of every **paid** order.
//   ///
//   /// Rules:
//   ///  - unpaid orders are ignored
//   ///  - a null list is treated as empty
//   ///
//   /// ```
//   /// double t = total(orders);
//   /// ```
//   ///
//   /// @param orders the orders to total, may be null
//   /// @return the sum, never negative
//   public static double total(List<Order> orders) { ... }
//
// The Java 21 equivalent, with the HTML you no longer have to write:
public class Main {
    /**
     * Returns the total of every <b>paid</b> order.
     * <p>
     * Rules:
     * <ul>
     *   <li>unpaid orders are ignored</li>
     *   <li>a null list is treated as empty</li>
     * </ul>
     *
     * @param values the amounts to total
     * @return the sum, never negative
     */
    static double total(double... values) {
        double sum = 0;
        for (double v : values) { if (v > 0) sum += v; }
        return sum;
    }

    public static void main(String[] args) {
        System.out.println("total: " + total(10.5, -3, 20));
        System.out.println("the HTML above is exactly what Markdown comments remove");
    }
}

Markdown Javadoc is one of the few Java 23 features that is final, not preview.