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

[Jonathan Gibbons]

On Tue, 3 Jan 2023 20:09:27 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 2:
> 
>> 1: /*
>> 2:  * Copyright (c) 2011, 2021, Oracle and/or its affiliates. All rights reserved.
> 
> 2011?

fixed, 2022, 2023

> src/jdk.compiler/share/classes/com/sun/source/doctree/package-info.java line 30:
> 
>> 28:  * trees (AST).
>> 29:  *
>> 30:  * <h2>Markdown</h2>
> 
> Consider updating the copyright years in this file.

done

> src/jdk.javadoc/share/classes/jdk/internal/org/commonmark/internal/util/Html5Entities.java line 15:
> 
>> 13: 
>> 14:     private static final Map<String, String> NAMED_CHARACTER_REFERENCES = readEntities();
>> 15:     private static final String ENTITY_PATH = "/org/commonmark/internal/util/entities.properties";
> 
> This properties file is missing from this PR. If you add a test with an md- doc comment that has entities (e.g. `&amp`), the test will crash.

fixed. 

Actually, the `.properties` file is not a Properties file as defined in `java.util.Properties` and is read line-at-a-time with custom code.  To avoid automated compilation of the file by the JDK build system, the file needs to avoid the `.properties` extension.  Currently, using plain old `.txt`.

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1248:
> 
>> 1246:     }
>> 1247: 
>> 1248:     private class MarkdownHandler {
> 
> Changes in this file seem to be the meat of the mechanism whereby Markdown-JavaDoc-HTML soup is handled. The mechanics looks good.

Thanks for checking.

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

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