30

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.
2
  • 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? Oct 31, 2014 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 1, 2014 at 18:18

8 Answers 8

44

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.

2
  • But I do want auto-formatting; and I need this to work for JavaDoc comments as well.
    – einpoklum
    Nov 1, 2014 at 18:18
  • what about XML/HTML files
    – Gerry
    Oct 13, 2021 at 23:00
16

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.

4
  • 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, 2012 at 14:38
  • I updated my answer to provide some alternatives (e.g. disabling the entire Javadoc formatting). Sep 25, 2012 at 16:01
  • Can you explain how the 'Indent Javadoc tags' can help me?
    – einpoklum
    Feb 17, 2014 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. Feb 17, 2014 at 18:54
12

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. enter image description here

Hope this Helps.

1
  • 1
    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) Oct 14, 2021 at 7:15
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.

1
  • 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, 2012 at 14:39
6

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>
 */
2
  • This will prevent the Eclipse formatter to apply the appropriate line width to these comments...
    – einpoklum
    Mar 24, 2015 at 20:12
  • 1
    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.
    – chaserb
    May 16, 2017 at 14:45
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>
 */
4
  • 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?
    – einpoklum
    Sep 26, 2012 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<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. Sep 26, 2012 at 18:46
  • Even if I make it a regular comment (/**), I still get the same behavior.
    – einpoklum
    Sep 26, 2012 at 18:51
  • 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>*/ Sep 26, 2012 at 19:00
1

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.

1
  • This will disable all block comment formatting - which I have indicated is not what I want. Please remove the answer.
    – einpoklum
    Sep 15, 2018 at 4:29
0

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.

4
  • 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, 2018 at 8: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, 2018 at 8: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, 2018 at 8:51
  • 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.
    – Naxos84
    May 30, 2018 at 9:06

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.