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

[Hannes Wallnöfer]

On Fri, 16 Feb 2024 00:46:34 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:
> 
>  - 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 and directly following a blockquote 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).

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

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