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

[Jonathan Gibbons]

On Wed, 4 Jan 2023 18:44:17 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> 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 ;-)

done

>> 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.

There was no perception that the Markdown machinery was particularly onerous, even in play scenarios in which all comments were treated as Markdown. Nevertheless, it seems reasonable to cache them within `MarkdownHandler`; less so in the enclosing `HtmlDocletWriter`.  It may be the case down the road that we want to configure the builders with settings that may vary between comments, so `MarkdownHandler` seems a good choice,

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

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