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

[Pavel Rappo]

On Mon, 9 Jan 2023 09:46:14 GMT, Andrey Turbanov <aturbanov 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.javadoc/share/classes/jdk/internal/org/commonmark/internal/Bracket.java line 48:
> 
>> 46:     public boolean bracketAfter = false;
>> 47: 
>> 48:     static public Bracket link(Text node, Position markerPosition, Position contentPosition, Bracket previous, Delimiter previousDelimiter) {
> 
> Let's use blessed modifiers order
> Suggestion:
> 
>     public static Bracket link(Text node, Position markerPosition, Position contentPosition, Bracket previous, Delimiter previousDelimiter) {

This class belongs to a 3rd party library, CommonMark. Changes that aren't necessary for the library to work in the JDK or not related to security might not be worth it.

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

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