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

[Jonathan Gibbons]

On Sat, 13 Jan 2024 21:55:06 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 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
>
> src/jdk.compiler/share/classes/com/sun/source/doctree/DocTreeVisitor.java line 257:
> 
>> 255:      *
>> 256:      * @implSpec Visits the provided {@code RawTextTree} node
>> 257:      * by calling {@code visitOther(node, p)}.
> 
> Nit: for consistency with the rest of the file, reorder `@param`-`@return` block with the `@implSpec` tag:
> 
> Suggestion:
> 
>      *
>      * @implSpec Visits the provided {@code RawTextTree} node
>      * by calling {@code visitOther(node, p)}.
>      *
>      * @param node the node being visited
>      * @param p a parameter value
>      * @return a result value

Done

> src/jdk.compiler/share/classes/com/sun/tools/javac/api/JavacTrees.java line 1080:
> 
>> 1078:             }
>> 1079: 
>> 1080:             private String info(FileObject fo) {
> 
> This does not seem to be used; is it for debugging? If so, add your `// DEBUG` comment.

It probably was used for debugging at some point.  The method can be `static`, meaning it is not specific to this class and could be elsewhere if we wanted to retain the functionality.   Code like this is easy enough to regenerate, so I will delete this copy for now.

> src/jdk.compiler/share/classes/com/sun/tools/javac/api/JavacTrees.java line 1156:
> 
>> 1154: 
>> 1155:     /**
>> 1156:      * {@return the {@linkplain ParserFactory} parser factory}.
> 
> Suggestion:
> 
>      * {@return the {@linkplain ParserFactory} parser factory}

done

> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/JavaTokenizer.java line 1065:
> 
>> 1063: 
>> 1064:                     if (accept('/')) { // (Spec. 3.7)
>> 1065:                         if (accept('/')) { // Markdown comment
> 
> I believe that some of the changes in `com/sun/tools/javac/parser` were contributed by @JimLaskey. If so, don't forget to add him as a co-author: `/contributor add jlaskey`.

did that

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484652974
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484650198
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484651230
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484651466