Repository navigation
formatter: Fenced codeblocks in markdown-style comments are not supported? #4209
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. ↩
Activity
fbricon commentedon Oct 13, 2025
Eclipse JDT doesn't mess with the fenced code block during formatting, so this is a bug in jdt.ls. @snjeza can you please take a look?
snjeza commentedon Oct 13, 2025
VS Code and Eclipse work the same way. The issue can be reproduced with JDK 23, 24 or 25.
fbricon commentedon Oct 13, 2025
@snjeza what about that:
eclipse-format-fenced-block.mp4
^^ is a java 25 project
snjeza commentedon Oct 14, 2025
Eclipse 4.38M1
jdk 25
fbricon25.mp4
jdk 21
fbricon21.mp4
snjeza commentedon Oct 14, 2025
VS Code JDK 21
fbriconvscode21.mp4
snjeza commentedon Oct 14, 2025
The issue can't be reproduced in Eclipse 4.37.
fbricon commentedon Oct 14, 2025
@snjeza thanks for checking. I opened eclipse-jdt/eclipse.jdt.core#4507
fbricon commentedon Oct 14, 2025
waiting for eclipse-jdt/eclipse.jdt.core#4418 to be merged upstream, then we can update jdt.ls with the fix
fbricon commentedon Jan 5, 2026
JDT.LS now includes eclipse-jdt/eclipse.jdt.core#4418, so this is fixed