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

[Jonathan Gibbons]

On Thu, 22 Feb 2024 14:53:11 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

>> 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 a more elegant solution can be found by restructuring the method to first check for `indent < currIndent` and then only having to check for new indented code blocks once.
> 
> 
>                 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>"""),

Thanks.  I will investigate your hint to look for a more elegant solution.  Thanks for the new test case.

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

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