RFR: JDK-8298405: Markdown support in the standard doclet

[Pavel Rappo]

On Wed, 4 Jan 2023 15:29:33 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Support for Markdown comments in the standard doclet.
>> 
>> To enable Markdown in a comment, start the comment with `/**md` followed by whitespace.  The syntax is as defined for CommonMark.
>> 
>> The work is in 3 parts:
>> 
>> 1. Update the Compiler Tree API to support Markdown tree nodes, containing strings of (uninterpreted) Markdown source code.
>> 2. Import commonmark-java into the `jdk.javadoc` module, to be able to convert Markdown strings to HTML.
>> 3. Update the standard doclet, to leverage the preceding two parts, to translate Markdown in documentation comments to `Content` nodes.
>> 
>> There are new tests both for the low level work in the Compiler Tree API, and for the overall high-level work in the doclet.
>
> src/jdk.compiler/share/classes/com/sun/source/doctree/MarkdownTree.java line 34:
> 
>> 32:  * The code may contain plain text, entities and HTML elements,
>> 33:  * all represented directly in the text of the code,
>> 34:  * but not {@linkplain InlineTagTree inline tags}.
> 
> IIUC, constructs represented by `BlockTagTree` are also NOT contained by this kind of node, right?

The fact that `MarkdownTree` is a terminal node and cannot be decomposed to constituent `DocTree`s is understood from its interface: the sole method of `MarkdownTree` returns `String`. It seems to me that that doc comment aims to convey that `MarkdownTree` never contains character input that belongs to `DocTree` of any other kind, such as `InlineTagTree`, or `BlockTagTree`. If so, then we should rephrase that part of the doc comment for clarity.

-------------

PR: https://git.openjdk.org/jdk/pull/11701