Java 23 Markdown Documentation Comments

Introduction Since Java 1.0, documentation comments have been written in HTML: <p> for paragraphs, <ul><li> for lists, {@code ...} or <code> for code. HTML is easy for the javadoc tool, but noisy to read in the source code, where developers actually see the comments most of the time. Meanwhile, Markdown has become the way developers write documentation everywhere else - README files, issues, wikis. Java 23Click to read tutorial: Overview of New Features in Java 23 (JEP 467) lets you write documentation comments in Markdown. This tutorial explains them with examples - the /// comment syntax, paragraphs, lists, code, tables and links to API elements, and how Javadoc's tags fit in - and generates the documentation to show the result. The /// syntax A Markdown documentation comment is a series of end-of-line comments starting with three slashes, ///, placed where a traditional /** ... */ comment would go. Traditional comments are unchanged and still use HTML, so both kinds can be mixed in a project, one comment at a time. The Markdown flavour is CommonMark, with GitHub-style tables. Here is a class documented both ways -
The same documentation in HTML and in Markdown
//Temperature.java
package demo;

/// Converts temperatures between units.
///
/// Supported units:
/// - `C` - degrees Celsius
/// - `F` - degrees Fahrenheit
///
/// | Celsius | Fahrenheit |
/// |---------|------------|
/// | 0       | 32         |
/// | 100     | 212        |
///
/// Results are returned as [Double] values; see [#toFahrenheit(double)].
public class Temperature {

  /**
   * Converts Celsius to Fahrenheit.
   * <p>
   * Uses the formula <code>F = C * 9 / 5 + 32</code>.
   *
   * @param celsius the temperature in degrees Celsius
   * @return the temperature in degrees Fahrenheit
   */
  public static double toFahrenheit(double celsius) {
    return celsius * 9 / 5 + 32;
  }

  /// Converts Fahrenheit to Celsius.
  ///
  /// Uses the formula `C = (F - 32) * 5 / 9`.
  ///
  /// @param fahrenheit the temperature in degrees Fahrenheit
  /// @return the temperature in degrees Celsius
  public static double toCelsius(double fahrenheit) {
    return (fahrenheit - 32) * 5 / 9;
  }
}
Explanation of the comments
  • Paragraphs are separated by a blank /// line - no <p> needed.
  • Lists use - or * (or 1. for numbered lists), and tables use the familiar pipe syntax.
  • Code is written with backticks, `like this`, or as a fenced code block with three backticks for multi-line examples. The @snippet tagClick to read: @snippet tag also works.
  • Links to API elements use Markdown reference links: [Double] links to the Double class, and [#toFahrenheit(double)] to a method of this class - replacing {@link ...}. Custom link text is written as [the conversion][#toCelsius(double)].
  • Javadoc tags such as @param, @return, @throws and @see work exactly as before, at the end of the comment.
Generating the documentation Nothing special is needed to generate documentation from Markdown comments - the javadoc tool in Java 23 and later recognizes the /// comments automatically - 
javadoc -d docs --source-path src demo
The class description in the generated Temperature.html shows that the Markdown was turned into ordinary HTML - a list, a table, and links -  Class description in the generated HTML (attributes removed for readability)
<p>Converts temperatures between units.</p>
<p>Supported units:</p>
<ul>
<li><code>C</code> - degrees Celsius</li>
<li><code>F</code> - degrees Fahrenheit</li>
</ul>
<table>
<thead>
<tr> <th>Celsius</th> <th>Fahrenheit</th> </tr> </thead>
<tbody>
<tr> <td>0</td> <td>32</td> </tr>
<tr> <td>100</td> <td>212</td> </tr> </tbody>
</table>
<p>Results are returned as <a><code>Double</code></a> values; see <a><code>toFahrenheit(double)</code></a>.</p>
On the rendered page this looks the same as documentation written in HTML. Both kinds of comment produce the same output, so a project can convert its comments gradually.
Things to know
  • Markdown comments are recognized only with ///; inside a traditional /** */ comment, Markdown syntax is not interpreted.
  • HTML can still be used inside a Markdown comment where Markdown has no equivalent, since CommonMark allows inline HTML.
  • Markdown's indented code blocks and leading spaces matter: the common indentation of the /// lines is removed, as in text blocks, but extra indentation is meaningful.
  • IDEs such as IntelliJ IDEA and Eclipse render Markdown documentation comments in their quick-documentation pop-ups, and can convert existing comments.
Summary In this tutorial we saw how Java 23 lets documentation comments be written in Markdown, using /// lines. We wrote paragraphs, lists, tables and code in Markdown, linked to API elements with reference links such as [Double] and [#toFahrenheit(double)], kept using Javadoc tags like @param, and generated the documentation to see the HTML produced. Next, read the overview of new features in Java 23Click to read tutorial: Overview of New Features in Java 23.