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.

Solution 1

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.

Solution 2

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.

Solution 3

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.

Solution 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>
 */

Solution 5

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.

View more solutions

Comments

[Glenn Strycker]

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?

[einpoklum]

@GlennStrycker: Well, since nobody's given me an acceptable answer, we're pretty much in the same boat for now :-(

[einpoklum]

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]

The point is that I do want block comment formatting. I just don't want it to mess up these parts of my comments.

[Zoltán Ujhelyi]

I updated my answer to provide some alternatives (e.g. disabling the entire Javadoc formatting).

[einpoklum]

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 <br> after my Notes:, and a <li> instead of ` - ` - I'd still have the same problem. Right?

[Bananeweizen]

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<ul><li>Item1</li><li>Item2</li></ul> 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.

[einpoklum]

Even if I make it a regular comment (/**), I still get the same behavior.

[Bananeweizen]

Enter this and run the formatter. It will format that as separate paragraph with a list of bullet items. /** headline<p>Notes:<ul><li>item1</li><li>item2</li></ul></p>*/

[einpoklum]

Can you explain how the 'Indent Javadoc tags' can help me?

[Zoltán Ujhelyi]

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.

[einpoklum]

But I do want auto-formatting; and I need this to work for JavaDoc comments as well.

[einpoklum]

This will prevent the Eclipse formatter to apply the appropriate line width to these comments...

[chaserb]

Note, there is a preference to toggle whether or not Eclipse will format the contents of a <pre> 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.

[einpoklum]

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.

[Naxos84]

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.

[einpoklum]

Yeah, that seems to be the case. But the 5 stars on this question indicate that many people would like it to be...

[Naxos84]

You could do something like this: github.com/google/google-java-format and then modify it to your needs. Though I have not tried it yet.

[einpoklum]

This will disable all block comment formatting - which I have indicated is not what I want. Please remove the answer.

[Gerry]

what about XML/HTML files

[Dharmendrasinh Chudasama]

Worked for me, exactly what i was looking for, changes=1: uncheck "Enable block comment formatting" & 2: Profile name (if it is not allowing with built in)