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

[Pavel Rappo]

On Mon, 8 Jan 2024 21:26:50 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 incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains seven additional commits since the last revision:
> 
>  - Merge with upstream/master
>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
>  - Address review comments
>  - Fix whitespace
>  - Improve handling of embedded inline taglets
>  - Customize support for Markdown headings
>  - JDK-8298405: Support Markdown in Documentation Comments

On CommonMark.

* `jdk.internal.md` contains 133 files, the vast majority of which are from commonmark-java 0.21.0. According to https://github.com/commonmark/commonmark-java/releases 0.21.0 is the latest/current release; good.

  Questions:

  * Did we take the tagged commit or mainline at some point after the tagged commit? If it's the latter, we need to take the tagged version.

  * What's the difference between those commonmark-java files in this PR and official commonmark-java? In other words, how do we adapt them? It would be nice to have a description of the procedure or a script to update those files.

* `jdk.internal.md` exports packages to `jdk.jshell`. A question for @lahodaj, who maintains `jdk.jshell`: when do we need to create a new PR similar to that withdrawn https://github.com/openjdk/jdk/pull/11936?

src/jdk.internal.md/share/classes/jdk/internal/markdown/MarkdownTransformer.java line 2:

> 1: /*
> 2:  * Copyright (c) 2005, 2023, Oracle and/or its affiliates. All rights reserved.

It's surprising to see 2005.

src/jdk.internal.md/share/classes/module-info.java line 29:

> 27:  * Internal support for Markdown.
> 28:  *
> 29:  * @since 22

Suggestion:

 * @since 23

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

PR Review: https://git.openjdk.org/jdk/pull/16388#pullrequestreview-1818084469
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1450342017
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1450347103