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

[Jonathan Gibbons]

On Wed, 24 Jan 2024 19:43:51 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.internal.md/share/classes/jdk/internal/markdown/MarkdownTransformer.java line 221:
> 
>> 219:                         }
>> 220:                         String code = t.getContent();
>> 221:                         // handle the (unlikely) case of FFFC characters existing in the code
> 
> For consistency with the rest of the file:
> Suggestion:
> 
>                         // handle the (unlikely) case of U+FFFC characters existing in the code

Fixed

> src/jdk.internal.md/share/classes/jdk/internal/markdown/MarkdownTransformer.java line 230:
> 
>> 228:                             start = pos + 1;
>> 229:                         }
>> 230:                         sourceBuilder.append(code.substring(start));
> 
> If I understood this correctly, it could be achieved simpler:
> Suggestion:
> 
>                             replacements.add(PLACEHOLDER);
>                             start = pos + 1;
>                         }
>                         sourceBuilder.append(code);

clever!

> src/jdk.internal.md/share/classes/jdk/internal/markdown/MarkdownTransformer.java line 353:
> 
>> 351:             return (equal(desc2, tree.description))
>> 352:                     ? tree
>> 353:                     : m.at(tree.pos).newReturnTree(tree.inline, desc2).setEndPos(tree.getEndPos());
> 
> Don't we need to set end position here only if the tag is in its inline variant?

It has an `endPos` field; we might as well set it.

> src/jdk.internal.md/share/classes/jdk/internal/markdown/MarkdownTransformer.java line 559:
> 
>> 557:         private boolean isReference(String s) {
>> 558:             try {
>> 559:                 var ref = refParser.parse(s, ReferenceParser.Mode.MEMBER_OPTIONAL);
> 
> Suggestion:
> 
>                 refParser.parse(s, ReferenceParser.Mode.MEMBER_OPTIONAL);

ok

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1472107834
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1472111878
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1472106632
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1472112635