JEP 467, Markdown Documentation Comments, has been promoted from Proposed to Target to Targeted for JDK 23. This feature proposes to enable JavaDoc documentation comments to be written in Markdown rather than a mix of HTML and JavaDoc @ tags. This will allow for documentation comments that are easier to write and read in source form.
This update's primary goal is to simplify the process of writing and reading documentation comments in Java source code. By allowing Markdown, which is known for its simplicity and readability, developers can avoid the complexities associated with HTML and JavaDoc tags. Existing documentation comments will remain unaffected, ensuring backward compatibility.
Furthermore, the update extends the Compiler Tree API, allowing other tools that analyze documentation comments to handle Markdown content effectively.
It’s important to note that this update does not include automated conversion of existing documentation comments to Markdown syntax. Developers must manually update their documentation to take advantage of the new feature.
Java documentation comments traditionally use HTML and JavaDoc tags, a practical choice in 1995 but has since become less convenient. HTML is verbose and challenging to write by hand, especially for developers who may not be familiar with it. Inline JavaDoc tags, such as {@link} and {@code}, are cumbersome and often require referencing documentation for proper usage.
Markdown, in contrast, is a lightweight markup language that is easy to read and write. It supports simple document structures like paragraphs, lists, styled text, and links, making it a suitable replacement for HTML in documentation comments. Additionally, Markdown allows the inclusion of HTML for constructs that it does not directly support, providing flexibility while reducing complexity.
Consider the following JavaDoc comment for java.lang.Object.hashCode written in the traditional format:
/**
* Returns a hash code value for the object. This method is
* supported for the benefit of hash tables such as those provided by
* {@link java.util.HashMap}.
* <p>
* The general contract of {@code hashCode} is:
* <ul>
* <li>Whenever it is invoked on the same object more than once during
* an execution of a Java application, the {@code hashCode} method
* must consistently return the same integer, provided no information
* used in {@code equals} comparisons on the object is modified.
* This integer need not remain consistent from one execution of an
* application to another execution of the same application.
* <li>If two objects are equal according to the {@link
* #equals(Object) equals} method, then calling the {@code
* hashCode} method on each of the two objects must produce the
* same integer result.
* <li>It is <em>not</em> required that if two objects are unequal
* according to the {@link #equals(Object) equals} method, then
* calling the {@code hashCode} method on each of the two objects
* must produce distinct integer results. However, the programmer
* should be aware that producing distinct integer results for
* unequal objects may improve the performance of hash tables.
* </ul>
*
* @implSpec
* As far as is reasonably practical, the {@code hashCode} method defined
* by class {@code Object} returns distinct integers for distinct objects.
*
* @return a hash code value for this object.
* @see java.lang.Object#equals(java.lang.Object)
* @see java.lang.System#identityHashCode
*/
This comment can be written in Markdown as follows:
/// Returns a hash code value for the object. This method is
/// supported for the benefit of hash tables such as those provided by
/// [java.util.HashMap].
///
/// The general contract of `hashCode` is:
///
/// - Whenever it is invoked on the same object more than once during
/// an execution of a Java application, the `hashCode` method
/// must consistently return the same integer, provided no information
/// used in `equals` comparisons on the object is modified.
/// This integer need not remain consistent from one execution of an
/// application to another execution of the same application.
/// - If two objects are equal according to the
/// [equals][#equals(Object)] method, then calling the
/// `hashCode` method on each of the two objects must produce the
/// same integer result.
/// - It is _not_ required that if two objects are unequal
/// according to the [equals][#equals(Object)] method, then
/// calling the `hashCode` method on each of the two objects
/// must produce distinct integer results. However, the programmer
/// should be aware that producing distinct integer results for
/// unequal objects may improve the performance of hash tables.
///
/// @implSpec
/// As far as is reasonably practical, the `hashCode` method defined
/// by class `Object` returns distinct integers for distinct objects.
///
/// @return a hash code value for this object.
/// @see java.lang.Object#equals(java.lang.Object)
/// @see java.lang.System#identityHashCode
Markdown documentation comments are indicated using /// at the beginning of each line instead of the traditional /** ... */ syntax. This helps to avoid conflicts with embedded /* ... */ comments in the examples, which is increasingly common in documentation comments.
The Markdown parser used in this implementation is the CommonMark variant, with enhancements to support linking to program elements and simple GFM (GitHub Flavored Markdown) pipe tables. JavaDoc tags can still be used within Markdown documentation comments, ensuring that existing JavaDoc features are retained.
The parsed documentation comments are represented by the com.sun.source.doctree package in the Compiler Tree API. To handle uninterpreted text, a new type of tree node, RawTextTree, is introduced, with a new tree-node kind, DocTree.Kind.MARKDOWN, indicating Markdown content. The implementation leverages the commonmark-java library to transform Markdown to HTML.
The introduction of Markdown support for JavaDoc comments marks a significant improvement in Java’s documentation capabilities, making it more accessible and easier to maintain. This change is expected to enhance developer productivity and improve the overall readability of Java documentation.