RFR: JDK-8298405: Support Markdown in Documentation Comments [v31]

[Pavel Rappo]

On Mon, 12 Feb 2024 23:52:35 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
>> 
>> Notable features:
>> 
>> * support for `///` documentation comments in `JavaTokenizer`
>> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
>> * updates to `DocCommentParser` to treat `///` comments as Markdown
>> * updates to the standard doclet to render Markdown comments in HTML
>
> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 40 commits:
> 
>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
>  - improve support for DocCommentParser.LineKind
>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 # Please enter a commit message to explain why this merge is necessary, # especially if it merges an updated upstream into a topic branch. # # Lines starting with '#' will be ignored, and an empty message aborts # the
>    commit.
>  - update copyright year on test
>  - refactor recent new test case in TestMarkdown.java
>  - address review feedback
>  - address review feedback
>  - added test case in TestMarkdown.java for handling of `@deprecated` tag
>  - amend comment in test
>  - improve comments on negative test case
>  - ... and 30 more: https://git.openjdk.org/jdk/compare/2ed889b7...1c64a6e0

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 563:

> 561: 
> 562:     /**
> 563:      * {@returns the plain-text content of a named HTML element in a list of content}

Suggestion:

     * {@return the plain-text content of a named HTML element in a list of content}

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 1021:

> 1019:                     .findFirst();
> 1020:             if (first.isEmpty() || first.get() != tree) {
> 1021:                 dct.getFirstSentence().forEach(t -> System.err.println(t.getKind() + ": >>|" + t + "|<<"));

Is it leftover debug output?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/Start.java line 571:

> 569:         // of a doclet to be specified instead of the name of the
> 570:         // doclet class and optional doclet path.
> 571:         // See https://bugs.openjdk.org/browse/JDK-8263219

It's hard to understand this:

> to permit an instance of an appropriately configured instance of a doclet

Also: how is that piece of code used? When I commented it out, no test/langtools:langtools_javadoc tests failed.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1487629102
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1487659843
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1487642764