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

[Hannes Wallnöfer]

On Thu, 22 Feb 2024 00:17:29 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 two additional commits since the last revision:
> 
>  - update DocCommentParser and tests to improve handling of code blocks and code spans in Markdown documentation comments
>  - fix indentation, for consistency

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 1373:

> 1371:                 while (indent < currIndent) {
> 1372:                     currIndent = indentStack.pop();
> 1373:                 }

This new Markdown class looks very good!

I think in this place we also need to check for indented code blocks, since we reduced `currIndent` and may have 4 or more character indentation compared to the new `currIndent` value. 

My tentative fix is to add the following code here, but maybe there's a more elegant solution by restructuring the method to first check for `indent < currIndent` and then for new indented code blocks.


                if (indent >= currIndent + 4 && !isParagraph(prevLineKind)) {
                    blockId++;
                    lineKind = LineKind.INDENTED_CODE_BLOCK;
                    return;
                }


The following could be added to `TestMarkdownCodeBlocks.java` to test this case:


            POST_LIST_INDENT(
                    """
                         1.  list item
                         
                             second paragraph
                       
                            {@code CODE}
                            @Anno

                        end""",
                    """
                        <ol>
                        <li>
                        <p>list item</p>
                        <p>second paragraph</p>
                        </li>
                        </ol>
                        <pre><code>{@code CODE}
                        @Anno
                        </code></pre>
                        <p>end</p>"""),

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

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