-
Notifications
You must be signed in to change notification settings - Fork 492
Description
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
-
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. ↩