On Wed, 11 Sep 2024 22:36:02 GMT, Jonathan Gibbons <[email protected]> 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
