How to prevent Eclipse formatter from messing up text-bulleted comments?

Question

I have (Java) comments such as:

/* 
 * The quick brown fox jumped over the lazy dog.
 *
 *
 * Notes:
 * - The quick brown fox jumped over the lazy dog. The quick brown fox
 *   jumped over the lazy dog. The quick brown fox jumped over the lazy
 *   dog.
 * - The second quick brown fox jumped over the lazy dog. The quick brown
 *   jumped over the lazy dog. The quick brown fox jumped over the lazy
 *   dog.
 */

The Eclipse auto-formatter sets the comment line width properly, but makes it:

/*
 * The quick brown fox jumped over the lazy dog.
 * 
 * 
 * Notes: - The quick brown fox jumped over the lazy dog. The quick brown fox jumped over the lazy
 * dog. The quick brown fox jumped over the lazy dog. - The second quick brown fox jumped over the
 * lazy dog. The quick brown jumped over the lazy dog. The quick brown fox jumped over the lazy dog.
 */

How do I the code formatter to leave the bulleted lists as-is, while still otherwise processing the comment?

Notes:

I don't want to turn off line joining in comments, because I do want my comment lines to be fit to the maximum length. So turning off line joining, or turning off formatting for Javadoc comments, or temporarily suspending autoformatting, are not acceptable solutions.
Possibly related question.

I'm having the same problem with Scala in Eclipse, but the solutions below are Java-specific, as the Scala code formatter tab has different options. Is there a way to turn off comment-reformatting for Scala? — Glenn Strycker, Oct 31 '14 at 18:44
@GlennStrycker: Well, since nobody's given me an acceptable answer, we're pretty much in the same boat for now :-( — einpoklum, Nov 01 '14 at 18:18

score 41 · Answer 1 · edited May 23 '17 at 10:31

41

This answer says that you add a hypen right after the opening /*, i.e.:

/*- 
 * The quick brown fox jumped over the lazy dog.
 *
 *
 * Notes:
 * - The quick brown fox jumped over the lazy dog. The quick brown fox
 *   jumped over the lazy dog. The quick brown fox jumped over the lazy
 *   dog.
 * - The second quick brown fox jumped over the lazy dog. The quick brown
 *   jumped over the lazy dog. The quick brown fox jumped over the lazy
 *   dog.
 */

This worked for me too.

edited May 23 '17 at 10:31

Community

1
1

answered May 20 '13 at 10:23

Varun Achar

13,274
7
53
71

But I do want auto-formatting; and I need this to work for JavaDoc comments as well. – einpoklum Nov 01 '14 at 18:18

score 15 · Answer 2 · edited May 23 '17 at 11:47

15

The answer to your question is probably the same as here: How to turn off the Eclipse code formatter for certain sections of Java code?

Since Eclipse 3.6 you can use the

// @formatter:off
...
// @formatter:on

annotations to disable code formatting.

Update:

Alternatively, you could also change the comment settings in the Preferences: in Java/Code Style/Formatter edit the formatter settings, and check the Comments page for the following settings:

Enable Javadoc formatting (General settings)
Indent Javadoc tags (Javadoc settings)

Btw, this kind of manual list does not translate into a list in the generated code. It might make sense to use a html list for this reason.

edited May 23 '17 at 11:47

Community

1
1

answered Sep 25 '12 at 07:54

Zoltán Ujhelyi

13,598
2
30
36

Well, that's kind of what I specified would not be a solution for me. I don't want to dirty my files like that, nor add two lines to every such comment... – einpoklum Sep 25 '12 at 14:38
I updated my answer to provide some alternatives (e.g. disabling the entire Javadoc formatting). – Zoltán Ujhelyi Sep 25 '12 at 16:01
Can you explain how the 'Indent Javadoc tags' can help me? – einpoklum Feb 17 '14 at 14:55
I am not sure, but I was hoping it would not change line breaks/indentation if turned off. If not, than sorry again for suggesting something that does not work. Sadly, the only foolproof solution is to define HTML lists; they will work, but will less easy to read in the Java source code. – Zoltán Ujhelyi Feb 17 '14 at 18:54

score 6 · Answer 3 · answered Sep 25 '12 at 11:17

6

You can make changes to how Eclipse formats comments and have special handling for block comments.

Got to Window -> preferences. Java > Code style > Formatter. Click on "New" to create a new template. Then under the tab "Comments" disable block comment formatting.

This will however never perform any formatting on block comments.

answered Sep 25 '12 at 11:17

Fredrik

10,407
5
43
78

The point is that I _do_ want block comment formatting. I just don't want it to mess up these parts of my comments. – einpoklum Sep 25 '12 at 14:39

Jafar Ali · Answer 4 · 2020-08-08T15:26:05.370

I know the question is old but, I can also see nobody gave a satisfactory answer.

This resolved my issue.

Go to Preference->Java->Code Style->Formatter. Here, go to Edit of whatever Formatter style you are using. In the Edit Dialog you will find a checkbox Enable Block Comment Formatting. Uncheck this. Change Profile name as I have done. Apply and OK. You are done.

Please refer to this below Image.

Hope this Helps.

score 4 · Answer 5 · answered Mar 23 '15 at 15:49

4

Picking up what Bananeweizen said, you could also wrap the relevant comment block with <pre></pre> tags, keeping every tab and space in it's place:

/* 
 * The quick brown fox jumped over the lazy dog.
 *
 *
 *<pre>Notes:
 * - The quick brown fox jumped over the lazy dog. The quick brown fox
 *   jumped over the lazy dog. The quick brown fox jumped over the lazy
 *   dog.
 * - The second quick brown fox jumped over the lazy dog. The quick brown
 *   jumped over the lazy dog. The quick brown fox jumped over the lazy
 *   dog.</pre>
 */

answered Mar 23 '15 at 15:49

actc

794
1
6
21

This will prevent the Eclipse formatter to apply the appropriate line width to these comments... – einpoklum Mar 24 '15 at 20:12

Note, there is a preference to toggle whether or not Eclipse will format the contents of a

 tag. I'm on Eclipse Neon (Mac), and the preference is under "Java | Code Style | Formatter." Once there, edit the active profile, and select the "Comments" tab. Make sure the "Format Java code snippets inside 'pre' tags" is unchecked if you want to prevent this formatting.

– chaserb May 16 '17 at 14:45

Bananeweizen · Answer 6 · 2012-09-27T05:56:49.037

2

In Java there are 2 different kinds of comments:

block comments: They have no standard format and are therefore formatted like floating text.
JavaDoc comments: Those have a common structure, and their formatting depends on the layout tags (like <br> or <p>) used in the comment.

In JavaDoc your example could be written like below (and would be formatted as shown):

/**
 * The quick brown fox jumped over the lazy dog.
 * 
 * <p>
 * Notes:
 * <ul>
 * <li>The quick brown fox jumped over the lazy dog. The quick brown fox jumped over the lazy dog. The quick brown
 * fox jumped over the lazy dog.</li>
 * <li>The second quick brown fox jumped over the lazy dog. The quick brown jumped over the lazy dog. The quick
 * brown fox jumped over the lazy dog.</li>
 * </ul>
 * </p>
 */

edited Sep 27 '12 at 05:56

answered Sep 26 '12 at 16:31

Bananeweizen

20,962
8
64
86

Well, you're both right and wrong. We don't yet compile Javadoc (in my team project), I'm trying to get that adopted. So for starters I haven't used the HTML markup. But supposing that I did, and I had a `
` after my `Notes:`, and a `
` instead of ` - ` - I'd still have the same problem. Right?

einpoklum

Sep 26 '12 at 18:31

1

If you start the comment with `/**` (2 stars!) then Eclipse will recognize this as JavaDoc and will format it according to the tags. You can then use `Notes

Item1
Item2

` for the list, which will be _rendered_ in the Eclipse hover like a bullet list. In the source it will be formatted with line breaks, but admittedly it is still not as readable like your own format. – Bananeweizen Sep 26 '12 at 18:46

Even if I make it a regular comment (`/**`), I still get the same behavior. – einpoklum Sep 26 '12 at 18:51

Enter this and run the formatter. It will format that as separate paragraph with a list of bullet items. `/** headline

Notes:

item1
item2

*/` – Bananeweizen Sep 26 '12 at 19:00

Naxos84 · Answer 7 · 2018-05-30T09:01:42.343

How about:

/**
 * The quick brown fox jumped over the lazy dog.
 *
 * <p>Notes:
 * <li>The quick brown fox jumped over the lazy dog. The quick brown fox jumped over the lazy dog. The quick brown fox jumped over the lazy dog.</li>
 * <li>The second quick brown fox jumped over the lazy dog. The quick brown jumped over the lazy dog. The quick brown fox jumped over the lazy dog.</li>
 */

And then turn of "Format HTML tags" in Windows -> Preferences -> Java -> Code Style -> Formatter -> Edit... -> Comments

This still does the line width line breaking.

EDIT:

I used the following block-comment:

/*
 * The quick brown fox jumped over the lazy dog.
 *
 * Notes:
 * - The quick brown fox jumped over the lazy dog. The quick brown fox jumped over the lazy dog. The quick brown fox jumped over the lazy dog. The quick brown fox jumped over the lazy dog.
 * - The second quick brown fox jumped over the lazy dog. The quick brown jumped over the lazy dog. The quick brown fox jumped over the lazy dog. The quick brown fox jumped over the lazy dog.
 */

I'm using Eclipse Neon.3 for Java EE and my Formatter cor comments is set to a width of 150 and "Never join lines" selected. Formatting this block comment gives me the following result which I think is what you might want (Though I know that you don't want to "never join lines").

/*
 * The quick brown fox jumped over the lazy dog.
 *
 * Notes:
 * - The quick brown fox jumped over the lazy dog. The quick brown fox jumped over the lazy dog. The quick brown fox jumped over the lazy dog. The
 * quick brown fox jumped over the lazy dog.
 * - The second quick brown fox jumped over the lazy dog. The quick brown jumped over the lazy dog. The quick brown fox jumped over the lazy dog.
 * The quick brown fox jumped over the lazy dog.
 */

There is just 1 small problem. When I add some more text to the first bulleted list and then formatting again I get the following result.

/*
 * The quick brown fox jumped over the lazy dog.
 *
 * Notes:
 * - The quick brown fox jumped over the lazy dog. The quick brown fox jumped over the lazy dog. The quick brown fox jumped over the lazy dog. The
 * SOME MORE TEXT TO WRAP
 * quick brown fox jumped over the lazy dog.
 * - The second quick brown fox jumped over the lazy dog. The quick brown jumped over the lazy dog. The quick brown fox jumped over the lazy dog.
 * The quick brown fox jumped over the lazy dog.
 */

That is because I told the formatter "not to join lines". When I unselect "Never join lines" I apparently get the same result as you have.

That's not a bad thing to do, but it's not what I asked.... I'm talking about existing code, existing comments, text bullets, no html tags. — einpoklum, May 30 '18 at 08:42
I'm sorry. So you would need something that recognizes "-" as indicator for a bulleted list. I don't think that the eclipse formatter can do this out of the box. — Naxos84, May 30 '18 at 08:47
Yeah, that seems to be the case. But the 5 stars on this question indicate that many people would like it to be... — einpoklum, May 30 '18 at 08:51
You could do something like this: https://github.com/google/google-java-format and then modify it to your needs. Though I have not tried it yet. — Naxos84, May 30 '18 at 09:06

score 0 · Answer 8 · edited Sep 15 '18 at 03:12

0

Specifically, you want to set:

org.eclipse.jdt.core.formatter.comment.format_block_comments=false

This is accessible somewhere in Eclipse settings, for VS Code, inside the root of the project you need a .settings directory, with a "org.eclipse.jdt.core.prefs" file that contains that line. This file would contain all your Eclipse settings that VS code leverages. This setting would apply similarly for other editors that use the Eclipse settings.

edited Sep 15 '18 at 03:12

Stephen Rauch

40,722
30
82
105

answered Sep 15 '18 at 02:46

jomamaxx

101
5

This will disable all block comment formatting - which I have indicated is not what I want. Please remove the answer. – einpoklum Sep 15 '18 at 04:29

How to prevent Eclipse formatter from messing up text-bulleted comments?

8 Answers8

Linked

Related