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

[Pavel Rappo]

On Fri, 16 Feb 2024 07:42:47 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:
>> 
>>  - Support for Table Of Contents in Markdown headings
>>  - fix typo
>
> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 286:
> 
>> 284:                         lineKind = (ch == '\n' || ch == '\r') ? LineKind.BLANK
>> 285:                                 : (indent <= 3) ? peekLineKind()
>> 286:                                 : lineKind != LineKind.OTHER ? LineKind.INDENTED_CODE_BLOCK
> 
> Doesn't this cause false positives for indented code blocks? In my understanding, indented lines [in a list context](https://spec.commonmark.org/0.30/#example-258) and [directly following a blockquote](https://spec.commonmark.org/dingus/?text=%3E%20%20%20%20foo%0A%20%20%20%20%20bar%0A) are not interpreted as code blocks, but as part of the list or blockquote. So my guess would be that `not OTHER` should be something like `BLANK or INDENTED_CODE_BLOCK or HEADER`, and that still leaves the problem of a [blank line in a list context](https://spec.commonmark.org/0.30/#example-108).

Sigh. I remember when we all hoped that we wouldn't need to go in the weeds of Markdown parsing, but here we are. Hannes is right. Here are a coupe of problematic examples:

 -     /// List
       ///
       ///   - item
       ///
       ///     @param

 -     /// > Quote
       /// >
       /// >     {@link java.lang.Object}

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

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