[Formatter] Recognise MarkDown headings, Lists, Comment Snippets & Tables in formatter #4418

SougandhS · 2025-09-22T10:35:28Z

This commits adds the support to recognize markdown headings, lists, comment fences & tables for formatter

fixes :
#4337

Lists

Lists.mp4

Headings

Headings.mp4

Snippets

SnippetMarkdown.mp4

What it does

How to test

Author checklist

I have thoroughly tested my changes
The change is following the coding conventions
I have signed the Eclipse Contributor Agreement (ECA)

SougandhS · 2025-09-22T10:39:03Z

Hi @mateusz-matela, please check this once you are available

mateusz-matela · 2025-09-22T13:23:41Z

I don't think a setting for this is necessary. It made more sense for html tags, as one can put spaces and newlines inside/around them in many different ways that make sense, so one may not want to use the formatter's standard. But for markdown elements there's pretty much only one sensible notation, wouldn't you agree?

Note that markdown also supports tables which require a similar approach: https://docs.oracle.com/en/java/javase/23/javadoc/using-markdown-documentation-comments.html#GUID-7269D6B1-BAA2-4260-A295-EBC3DDA3E69C

After a glance at the code I can say that the new code would better fit in a separate handleMarkdown() method that begins with if-return similar to handleHtml().

SougandhS · 2025-09-22T13:30:26Z

But for markdown elements there's pretty much only one sensible notation, wouldn't you agree?

Then I guess I'll remove the UI and option changes 👍

mateusz-matela · 2025-09-22T13:32:42Z

Then I guess I'll remove the UI and option changes 👍

maybe this point is actually even stronger - if the setting is turned off, the formatter would mangle the headers and lists into one line, resulting in completely different javadoc content? Nobody would want that!

As for tables - I guess they are much more complicated due to columns alignment - maybe that could be a separate issue (with an on/off setting this time?), but for now we'd need to at least detect them to make sure they are not touched.

SougandhS · 2025-09-22T13:33:07Z

Note that markdown also supports tables which require a similar approach: https://docs.oracle.com/en/java/javase/23/javadoc/using-markdown-documentation-comments.html#GUID-7269D6B1-BAA2-4260-A295-EBC3DDA3E69C

Yes, and different types of comments too https://docs.oracle.com/en/java/javase/23/javadoc/using-markdown-documentation-comments.html#GUID-7E6D6A81-1176-4CF2-85EE-97A86ACDA351

this I will do in another PR. I had hard time implementing this

SougandhS · 2025-09-22T13:37:00Z

maybe this point is actually even stronger - if the setting is turned off, the formatter would mangle the headers and lists into one line, resulting in completely different javadoc content? Nobody would want that!

Agreed :D

As for tables - I guess they are much more complicated due to columns alignment - maybe that could be a separate issue (with an on/off setting this time?), but for now we'd need to at least detect them to make sure they are not touched.

Lists where complicated too due to indent style, but was manageable. For table pattern recognition do you have any suggestions ?

org.eclipse.jdt.core/formatter/org/eclipse/jdt/internal/formatter/CommentsPreparator.java

SougandhS · 2025-10-02T02:47:56Z

Hi @mateusz-matela
I have added support for formatting markdown Snippets comments & Tables

Snippets

SnippetMarkdown.mp4

Tables

for tables currently the formatter recognise the pattern, however it still have some issues in processing column arrangement but it wont break the table structure now.

TableMarkdown.mp4

Could you please check the new changes ?

SougandhS · 2025-10-02T02:49:28Z

Unrelated test failure org.eclipse.jdt.core.tests.model.ClasspathTests.testInvalidClasspath1

mateusz-matela

for tables currently the formatter recognise the pattern, however it still have some issues in processing column arrangement but it wont break the table structure now.

I think full support would mean parsing the whole table, reformatting contents of each cell and determining width of each column as max width of column's cells in order to align everything. This would require a setting as someone my want to keep their unconventional alignment for some reason. I'm not sure it makes sense to implement a partial solution for now, it would be enough to leave tables untouched (as if the new setting is off)

....jdt.core.tests.model/src/org/eclipse/jdt/core/tests/formatter/FormatterRegressionTests.java

org.eclipse.jdt.core/formatter/org/eclipse/jdt/internal/formatter/CommentsPreparator.java

org.eclipse.jdt.core/formatter/org/eclipse/jdt/internal/formatter/TokenManager.java

org.eclipse.jdt.core/formatter/org/eclipse/jdt/internal/formatter/TextEditsBuilder.java

....jdt.core.tests.model/src/org/eclipse/jdt/core/tests/formatter/FormatterRegressionTests.java

org.eclipse.jdt.core/formatter/org/eclipse/jdt/internal/formatter/CommentsPreparator.java

mateusz-matela · 2025-12-02T21:46:35Z

I see 3 failures with this patch, Could you please check that too ?

Oh right, good new tests ;) Fixed with mateusz-matela@e1815a5

SougandhS · 2025-12-04T07:56:27Z

I see 3 failures with this patch, Could you please check that too ?

Oh right, good new tests ;) Fixed with mateusz-matela@e1815a5

I tried out the new changes but yet its failing with 195c200 :(

mateusz-matela · 2025-12-04T17:33:04Z

I tried out the new changes but yet its failing with 195c200 :(

Hmm, I just cherry picked my last two commits on top of yours and all tests pass :)
See https://github.com/mateusz-matela/eclipse.jdt.core-dev/commits/MarkdownLists/

SougandhS · 2025-12-08T04:35:14Z

@mateusz-matela I have added both of the commits now 👍

org.eclipse.jdt.core/formatter/org/eclipse/jdt/internal/formatter/CommentsPreparator.java

mateusz-matela · 2025-12-09T17:47:52Z

org.eclipse.jdt.core/formatter/org/eclipse/jdt/internal/formatter/CommentsPreparator.java

+			int endPos = -1;
+			int tokenIndexLast = -1;
+			Token closingToken = null;
+			boolean shouldDisable = false;


found in CommonMark spec:

If the end of the containing block (or document) is reached and no closing code fence has been found, the code block contains all of the lines after the opening code fence until the end

So maybe it was good to init with shouldDisable = true but also closing Token should init as the last token in the comment

Let me check this.. it looks like a very tricky edge case

Handled this case now 👍

org.eclipse.jdt.core/formatter/org/eclipse/jdt/internal/formatter/CommentsPreparator.java

mateusz-matela · 2025-12-09T17:53:11Z

org.eclipse.jdt.core/formatter/org/eclipse/jdt/internal/formatter/CommentsPreparator.java

+				String fenceCharsEnd = matcher.group(1); // the fence itself
+			    int fenceLengthEnd = fenceCharsStart.length();
+				// Check if fences match
+				if (!fenceCharsStart.equals(fenceCharsEnd))


could also check if there's no equivalent of info string after the closing fence, turns out it is not allowed

huh, it's also not allowed to have more than 3 spaces in front of a fence, not counting any indentation coming from lists. So code blocks analysis would need to be part of handleMarkdownList... So maybe that's for later :P

Will check this later then..

org.eclipse.jdt.core/formatter/org/eclipse/jdt/internal/formatter/CommentsPreparator.java

SougandhS · 2025-12-15T03:50:53Z

@mateusz-matela If there are no more major issues shall we proceed with current state ?

iloveeclipse · 2025-12-16T10:14:12Z

@SougandhS : not sure why this was assigned to me, I've undit that. I have no insights into the "formatter" domain area.

mateusz-matela · 2025-12-20T15:34:02Z

The fenced blocks implementation become quite complex, so I thought I'd have a try at the target solution and integrate it with the lists implementation: mateusz-matela@e344bd9
This fixed a few problems, as reflected it tests changes (you thought that 2 ticks made a valid code block fence)?
I think with these changes the PR will be ready to merge at last.

SougandhS · 2026-01-01T05:03:07Z

The fenced blocks implementation become quite complex, so I thought I'd have a try at the target solution and integrate it with the lists implementation: mateusz-matela@e344bd9 This fixed a few problems, as reflected it tests changes (you thought that 2 ticks made a valid code block fence)? I think with these changes the PR will be ready to merge at last.

Thanks, I have added the changes

This commits adds the support to recognize markdown Headings, Lists, Fences & Tables for formatter Fixes : eclipse-jdt#4337

SougandhS · 2026-01-02T03:39:19Z

Thanks a lot for the thorough review @mateusz-matela !
Merging this now 👍

SougandhS mentioned this pull request Sep 22, 2025

[Formatter] Add option for enablement of MarkDown tags formatting eclipse-jdt/eclipse.jdt.ui#2508

Closed

3 tasks

SougandhS requested a review from mateusz-matela September 22, 2025 10:38

SougandhS force-pushed the MDTagPatternRecgLists branch from f92dfce to bf1e64b Compare September 29, 2025 01:49

github-advanced-security bot found potential problems Sep 30, 2025

View reviewed changes

org.eclipse.jdt.core/formatter/org/eclipse/jdt/internal/formatter/CommentsPreparator.java Fixed Show fixed Hide fixed

github-advanced-security bot found potential problems Sep 30, 2025

View reviewed changes

org.eclipse.jdt.core/formatter/org/eclipse/jdt/internal/formatter/CommentsPreparator.java Fixed Show fixed Hide fixed

SougandhS force-pushed the MDTagPatternRecgLists branch 9 times, most recently from ce5d986 to b628847 Compare October 1, 2025 07:28

SougandhS changed the title ~~[Formatter] Recognise MarkDown headings & Lists in formatter~~ [Formatter] Recognise MarkDown headings, Lists & Comment Snippets in formatter Oct 1, 2025

SougandhS force-pushed the MDTagPatternRecgLists branch from b628847 to eb48ce3 Compare October 1, 2025 14:34

SougandhS changed the title ~~[Formatter] Recognise MarkDown headings, Lists & Comment Snippets in formatter~~ [Formatter] Recognise MarkDown headings, Lists, Comment Snippets & Tables in formatter Oct 1, 2025

SougandhS force-pushed the MDTagPatternRecgLists branch 2 times, most recently from 84dda38 to 86b0e4f Compare October 2, 2025 01:43

mateusz-matela requested changes Oct 6, 2025

View reviewed changes

SougandhS force-pushed the MDTagPatternRecgLists branch 2 times, most recently from 085f2f3 to 76a755f Compare October 12, 2025 06:09

SougandhS force-pushed the MDTagPatternRecgLists branch from a7f4eff to b277e18 Compare December 2, 2025 08:21

SougandhS force-pushed the MDTagPatternRecgLists branch from b277e18 to 195c200 Compare December 4, 2025 07:54

SougandhS force-pushed the MDTagPatternRecgLists branch from 195c200 to 7616659 Compare December 6, 2025 06:07

SougandhS requested a review from mateusz-matela December 8, 2025 04:33

SougandhS force-pushed the MDTagPatternRecgLists branch from 7616659 to b7b2e0c Compare December 8, 2025 04:33

SougandhS added this to the 4.39 M1 milestone Dec 8, 2025

mateusz-matela requested changes Dec 9, 2025

View reviewed changes

SougandhS force-pushed the MDTagPatternRecgLists branch 3 times, most recently from 25ea122 to baae5f9 Compare December 12, 2025 06:43

SougandhS requested a review from mateusz-matela December 12, 2025 08:03

garretwilson mentioned this pull request Dec 13, 2025

New Markdown Javadoc formatter incorrectly merges code blocks into preceding line #4694

Closed

subyssurendran666 assigned iloveeclipse Dec 16, 2025

iloveeclipse removed their assignment Dec 16, 2025

SougandhS force-pushed the MDTagPatternRecgLists branch 3 times, most recently from 8afb6e8 to 3a0e8b0 Compare January 1, 2026 03:40

mateusz-matela approved these changes Jan 1, 2026

View reviewed changes

Recognize MarkDown headings, Lists, Fences & Tables

582da6b

This commits adds the support to recognize markdown Headings, Lists, Fences & Tables for formatter Fixes : eclipse-jdt#4337

SougandhS force-pushed the MDTagPatternRecgLists branch from 3a0e8b0 to 582da6b Compare January 2, 2026 01:07

SougandhS merged commit df7f21e into eclipse-jdt:master Jan 2, 2026
13 checks passed

[Formatter] Recognise MarkDown headings, Lists, Comment Snippets & Tables in formatter #4418

[Formatter] Recognise MarkDown headings, Lists, Comment Snippets & Tables in formatter #4418

Uh oh!

Conversation

SougandhS commented Sep 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Lists

Headings

Snippets

What it does

How to test

Author checklist

Uh oh!

SougandhS commented Sep 22, 2025

Uh oh!

mateusz-matela commented Sep 22, 2025

Uh oh!

SougandhS commented Sep 22, 2025

Uh oh!

mateusz-matela commented Sep 22, 2025

Uh oh!

SougandhS commented Sep 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SougandhS commented Sep 22, 2025

Uh oh!

Uh oh!

Uh oh!

SougandhS commented Oct 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Snippets

Tables

Uh oh!

SougandhS commented Oct 2, 2025

Uh oh!

mateusz-matela left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mateusz-matela commented Dec 2, 2025

Uh oh!

SougandhS commented Dec 4, 2025

Uh oh!

mateusz-matela commented Dec 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SougandhS commented Dec 8, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mateusz-matela Dec 9, 2025

Choose a reason for hiding this comment

Uh oh!

SougandhS Dec 10, 2025

Choose a reason for hiding this comment

Uh oh!

SougandhS Dec 12, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mateusz-matela Dec 9, 2025

Choose a reason for hiding this comment

Uh oh!

mateusz-matela Dec 9, 2025

Choose a reason for hiding this comment

Uh oh!

SougandhS Dec 10, 2025

SougandhS commented Sep 22, 2025 •

edited

Loading

SougandhS commented Sep 22, 2025 •

edited

Loading

SougandhS commented Oct 2, 2025 •

edited

Loading

mateusz-matela commented Dec 4, 2025 •

edited

Loading