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

[Jonathan Gibbons]

On Fri, 26 Jan 2024 16:33:08 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 668:
> 
>> 666:          * U+FFFC characters that were found in the original document.
>> 667:          */
>> 668:         Iterator<?> replaceIter;
> 
> Suggestion:
> 
>         final Iterator<?> replaceIter;

actually, `private final` ... done

> src/jdk.internal.md/share/classes/jdk/internal/markdown/MarkdownTransformer.java line 732:
> 
>> 730:                 offsets.add(m.end());
>> 731:             }
>> 732:             sourceLineOffsets = offsets.stream().mapToInt(Integer::intValue).toArray();
> 
> Here's an alternative, which you might find better (or not):
> Suggestion:
> 
>             sourceLineOffsets = Stream.concat(Stream.of(0), lineBreak.matcher(source).results()
>                             .map(MatchResult::end)).mapToInt(Integer::intValue).toArray();

done

it's borderline (to me) that it's worthwhile but given that my original code used streams to create the final array, it sort-of makes sense to go "all in".

> src/jdk.internal.md/share/classes/jdk/internal/markdown/MarkdownTransformer.java line 831:
> 
>> 829:         /**
>> 830:          * {@return the position in the original comment for a position in {@code source},
>> 831:          * using {@link #replaceAdjustPos}}.
> 
> Suggestion:
> 
>          * using {@link #replaceAdjustPos}}

done

> src/jdk.internal.md/share/classes/jdk/internal/markdown/MarkdownTransformer.java line 939:
> 
>> 937: 
>> 938:         /**
>> 939:          * Flush any text in the {@code text} buffer, by creating a new
> 
> Suggestion:
> 
>          * Flushes any text in the {@code text} buffer, by creating a new

done

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1473668136
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1473670108
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1473668952
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1473668548