RFR: 8338525: Leading and trailing code blocks by indentation

[Pavel Rappo]

On Wed, 11 Sep 2024 22:36:02 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review these changes to correct the handling of leading and trailing indented code blocks in a doc comment.
> 
> There are two separate issues here: one for leading indented code blocks and one for trailing indented code blocks.
> 
> 1. Leading indented code blocks: the code to detect the first sentence of a doc comment is modified to detect whether the comment begins with an indented code block. If it does, the first sentence is deemed to be empty, and the body of the doc comment begins with the code block.
> 2. Trailing indented code blocks: the content of the indented code block is marked as significant by updating `lastNonWhite`, which will cause the content to be recorded (not dropped) if the code block is followed by EOF.
> 
> For both cases, simple `DocTree` AST-level tests are provided, as well as full `JavadocTester` tests, that test the end-user view of the generated docs.

Looks good.

src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DocTreeMaker.java line 596:

> 594:                             var content = getContent(dt);
> 595:                             if (isFirst && dt.getKind() == Kind.MARKDOWN && isIndented(content)) {
> 596:                                 // begins with an indented code block (unusual), so no first sentence

This reminded me of the `snippet` tag, which, in similar circumstances, will be included in the first sentence.

test/langtools/jdk/javadoc/doclet/testMarkdown/TestMarkdownCodeBlocks.java line 497:

> 495:                     package p;
> 496:                     ///     Leading code block
> 497:                     /// Lorum ipsum.

My immediate reaction was to think that it is not a code block because there's no blank line between those two lines; but it is: https://spec.commonmark.org/0.31.2/#example-114

So, all is well here.

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

Marked as reviewed by prappo (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/20956#pullrequestreview-2299962785
PR Review Comment: https://git.openjdk.org/jdk/pull/20956#discussion_r1756688209
PR Review Comment: https://git.openjdk.org/jdk/pull/20956#discussion_r1756634553