Summary

Support Markdown in documentation comments processed by javadoc's Standard Doclet.

Problem

While HTML has been the standard for rich text in documentation comments since forever, it is a cumbersome format to read and edit in the source code, Markdown is becoming a de-facto standard for "simple" rich text, as typically found in documentation comments. It would be good to be able to support Markdown in documentation comments.

Solution

A new style of documentation comment consisting of a series of consecutive lines each beginning with /// is recognized as being a Markdown comment.

Within a Markdown comment, the following applies:

• The overall syntax for the comment remains that of a description, optionally followed by block tags.

• In the description, and in any tags that can contain rich text, the syntax is that of CommonMark interspersed with standard and user-defined inline tags.

• Inline and block tags are parsed and processed individually, and then treated as opaque objects in the enclosing context. (The intent and net effect is that you cannot use syntactic Markdown forms that partially overlap with any tag.)

• The content of Markdown code spans and code blocks is treated as literal text, and so inline and block tags are not recognized within code spans and code blocks.

• Reference links are extended to allow simple references to program elements.

• There is no special handling for &, to introduce an entity, or < to introduce an HTML start or end element. Entities and HTML elements may still appear, but will be treated as part of the Markdown code, and processed as such.

Disabling /// comments

An investigation of publicly available source code indicates that some developers already use /// in ways that may be incompatible with the new use for documentation comments. For those situations where it may be undesirable to modify existing comments, a new option for both javac and javadoc will be provided, to disable recognition of comments beginning with /// as documentation comments.

Specification

The changes to the API specifications and to the Document Comment Specification for the Standard Doclet are attached. (Latest version: 07) The specifications can also be seen here:

• apidiff.07: API changes, in apidiff format
• specdiff-api.07: API changes, in specdiff format
• specdiff-dcs.07 Changes to the Document Comment Specification for the Standard Doclet
• specdiff-man.07 Changes to the JavaDoc Tool Guide (man page)

Note: the changes to the Document Comment Specification for the Standard Doclet primarily consist of including relevant parts of the associated JEP into this document, along with some minor cosmetic changes. There should be no significant differences between the specification detailed here and in the JEP.

Disabling /// comments

The following is added to the javac man page:

+<a id="option-disable-line-doc-comments">`--disable-line-doc-comments`</a>
+:   Disables support for documentation comments with lines beginning ///.
+
 <a id="option-Djava.endorsed.dirs">`-Djava.endorsed.dirs=`*dirs*</a>

A corresponding entry is added to the list of "pass-through" options for javac on the javadoc man page:

 * <span id="option-class-path">`--class-path`, `-classpath`, or `-cp`</span>
+* <span id="option-disable-line-doc-comments">`--disable-line-doc-comments`</span>
 * <span id="option-enable-preview">`--enable-preview`</span>

java.compiler/javax.lang.model.util.Elements

javax.lang.model.util.Elements contains a method getDocComment(Element) that defines the form of a documentation comment. This method is updated to include the new /// form. A new method is added to determine the kind of documentation comment used for an element. These changes are described separately, in JDK-8329632.