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

[Jonathan Gibbons]

On Fri, 26 Jan 2024 18:14:05 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains eight commits:
>> 
>>  - Merge with upstream/master
>>  - 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
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/CommentUtils.java line 629:
> 
>> 627:     public DocCommentTree parse(URI uri, String text) {
>> 628:         return trees.getDocCommentTree(new SimpleJavaFileObject(
>> 629:                 uri, JavaFileObject.Kind.HTML) {
> 
> Was it a bug before?

I would describe it as having been a "latent bug, waiting to happen".

Previously, all file objects were regarded as containing HTML content, and so there was no need to use the parameter, although maybe it would have been good to check it.

Now, file objects can be HTML or Markdown, and so we do need to use the parameter.

In the case here, the method is used on strings specified in command-line options, which are specified to be in HTML format.   Yes, we might want to change that, but that would be a different RFE separate from the work in this PR.  In that future evolution, I would suggest adding a `JavaFileObject.Kind` parameter to parse and/or inferring the kind from the tail of the path in the `uri` parameter.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1483458107