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

[Jonathan Gibbons]

On Thu, 1 Feb 2024 01:12:52 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 incrementally with four additional commits since the last revision:
> 
>  - MarkdownTransformer: tweak doc comments
>  - MarkdownTransformer: change `Lower.replaceIter` to be `private final`
>  - MarkdownTransformer: use suggested text for using streams
>  - remove obsolete debug code

> 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 [8299902: Support for MarkDown javadoc in JShell #11936](https://github.com/openjdk/jdk/pull/11936)?

Added comment to `jdk.internal.md` `module-info.java`

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

PR Comment: https://git.openjdk.org/jdk/pull/16388#issuecomment-1922295907