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

[Jonathan Gibbons]

On Tue, 3 Jan 2023 21:20:20 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/tools/javac/tree/DocPretty.java line 214:
> 
>> 212:                 for (DocTree node : nodes) {
>> 213:                     Boolean b = scan(node, ignore);
>> 214:                     if (b != null && b.equals(Boolean.TRUE)) {
> 
> Could it be `b == Boolean.TRUE`?

In general, no, because of the possibility of `new Boolean` so it will depend on the code in `scan`. I'll investigate.

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1249:
> 
>> 1247: 
>> 1248:     private class MarkdownHandler {
>> 1249:         private static final char FFFC = '\uFFFC'; // Unicode Object Replacement Character
> 
> Can we use a better name for the FFFC constant? PLACEHOLDER or some such.

Sure.   At least I took the first step and avoided repeated use of the character constant ;-)

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1281:
> 
>> 1279:             Node document = parser.parse(markdownInput.toString());
>> 1280:             HtmlRenderer renderer = HtmlRenderer.builder().build();
>> 1281:             String markdownOutput = renderer.render(document);
> 
> Curious how heavyweight the parser and renderer are; should we cache them for reuse?

Seems like a good idea if all works as might be expected.

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

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