Skip to content

formatter: Fenced codeblocks in markdown-style comments are not supported? #4209

@dbarenholz

Description

@dbarenholz

Description

If you have a markdown comment using the triple slashes \\\ 1 and have a fenced codeblock inside of it, then the formatter does not respect the fact that a fenced codeblock is an inherently multiline structure/block. While the JEP for this feature (markdown comments) never explicitly mentions that fenced codeblocks are to be supported, it does give examples with them (CTRL+F for code block on the JEP page), and gives the impression that they should be supported. I think it's a reasonable assumption that fenced codeblocks should work in markdown comments.

Expected / Desired behaviour

Given a markdown comment with a codeblock, such as the one below, we expect the codeblock to stay "intact".

/// A markdown comment, with a codeblock.
/// ```java
/// void foo() {
///   System.out.println("Hello, World!"); // 2 spaces indented
/// }
/// ```
class Foo { }

Actual behaviour

The comment gets formatted to the thing shown below, breaking the codeblock.

/// A markdown comment, with a codeblock. ```java void foo() {
/// System.out.println("Hello, World!"); // 2 spaces indented } ```
class Foo {
}

On Reproducability

In order for this "bug" to exhibit itself, you must use a project with sufficiently high enough JDK version such that the linked JEP is no longer in preview (or enable preview). I suggest simply using JDK 25.

If the project uses a JDK that supports markdown comments, you can reproduce the issue by copy pasting the first codeblock under desired behaviour into a Java file, and running the formatter on it. Since it is considered javadoc, it will always be formatted, regardless of "format block comments" (or others) being enabled/disabled.

Footnotes

  1. Note that this is almost always considered a "javadoc" type comment, unless it is the first line of a file, in which case it would be a "header" type comment -- it is impossible for it to be interpreted as "block" or "line" type comments. We could argue whether or not this is a smart decision and/or naming scheme, but that's besides the point of this issue.

Metadata

Metadata

Assignees

Type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions