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

[Jonathan Gibbons]

On Thu, 22 Feb 2024 15:14:32 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> 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.

>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.

This seems wrong. Surely, we should not reduce the indentation and then for the same line in the comment check for an extra-indented line. Or else I am missing something.

That being said, thanks for the test case. I will investigate it.

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

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