Making Eclipse's Java code formatter ignore block comments

小开

It is language-dependent.

For example, if working with javascript, you would go to "Window -> Preferences -> Javascript -> Code Style -> Formatter" and then edit the formatter options.

Edit (reflecting changesin OP Questions

For editing java code formatting, go to "Window -> Preferences -> Java -> Code Style -> Formatter"

At the top of the panel you will see

Active Profile:
Eclipse [built-in]

From there you have one button to the right, "Edit", and two below, "New..." and "Import...". I would recommend Editing the existing profile.

In the edit profile dialog, there are a series of tabs along the top. The last tab is "Comments". To completely disable comment formatting, uncheck "Enable Javadoc comment formatting", "Enable block comment formatting", "Enable line comment formatting", and "Enable header comment formatting".

小开

In Eclipse 3.4: Preferences, Java->Code Style->Formatter, then edit profile, comments tab. There's a bunch of options there for controlling comment formatting.

小开

最佳答案

Update 2010, as pointed by the OP and in this answer, the special string // @formatter:off in Eclipse 3.6 is enough.

It was not available at the time of the question.

Original answer: June 2009, Eclipse 3.4/3.5

With the Java Formatter (Windows > Preferences > Java > Code Style > Formatter), you can create a new Formatter profile.

In the Comments tab (in eclipse3.5), you can make sure, in the "Javadoc comment settings", to uncheck "Format HTML tags".
Check also the "Never join lines" in the "General settings" section.

Then your comment should be written as:

/**
* PSEUDOCODE
* Read in user's string/paragraph
*
* Three cases are possible:
* <dl>
*   <dt>Case 1: foobar</dt>
*     <dd>        do case 1 things</dd>
*   <dt>Case 2: fred hacker</dt>
*     <dd>        do case 2 things</dd>
*   <dt>Case 3: cowboyneal</dt>
*     <dd>        do case 3 things</dd>
* </dl>
* In all cases, do some other thing
*/

Note: I have made a Javadoc comment, and not a simple comment, as I believe a comment with that much text in it may be better placed in front of a method. Plus, Javadoc sections have more formatting parameters to play with.
If it is in front of a method (true Javadoc), the HTML tags ABC0, ABC1 and <dd> will help to present it properly within the Javadoc view.

小开

Surround the specific text with <pre> </pre> tags.

小开

There is another solution that you can use to suppress the formatting of specific block comments. Use /*- (note the hyphen) at the beginning of the block comment, and the formatting won't be affected if you format the rest of the file.

/*-
* Here is a block comment with some very special
* formatting that I want indent(1) to ignore.
*
*    one
*        two
*            three
*/

Source: http://www.oracle.com/technetwork/java/javase/documentation/codeconventions-141999.html#350

小开

I just learned from a co-worker that Eclipse offers special formatting tags that can be used for this:

// @formatter:off
/*
* ╔════════╦═══════╦══════════╗
* ║ Month  ║ Sales ║ Position ║
* ╠════════╬═══════╬══════════╣
* ║ June   ║ 44k   ║ 2nd      ║
* ║ July   ║ 39k   ║ 2nd      ║
* ║ August ║ 49k   ║ 4th      ║
* ╚════════╩═══════╩══════════╝
*
* This comment shouldn't be formatted, and will now be ignored by the formatter.
*/
// @formatter:on

Note that you may need to manually enable this feature through the Preferences menu → Java > Code Style > Formatter, clicking on Edit, selecting the Off/On Tags tab and checking Enable Off/On tags (source).

A quick Google for the string @formatter:off brought me to this other SO answer, which mentioned this feature in the context of disabling the formatter for code blocks. I've confirmed that it works for line comments, "normal" block comments and Javadoc block comments as well.

小开

Another possibility is to use HTML's <pre> in Javadoc:

/**
* <pre>
*    this
*   is
*      kept
*  as
*    is
* </pre>
*/

At least this is how I tend to embed my ASCII-art in source code comments :)

小开

If you want to supress formatting in eclipse, you can always wrap content that is intended to NOT TO BE FORMATED into <pre>UNFORMATTED CONTENT</pre> tag. Javadoc formatter will detect that tag, and leave everything between that tags unformatted.

Pros:

Rest of Javadoc is still formatted
Javadoc's html output will be "unformatted" as well because of pre tags

Cons:

Not seeing one

小开

one workaround is to add pre tag for the comments that you don't want eclipse to format

/**
* <pre>
*    this part
*   is
*      out of
*  format
*
* </pre>
*/

小开

You can change this in Windows - Preferences - Java - Code Style - Formatter, than click the Edit.. button, find Comments, choose the Never Join Lines.

Then, it should be OK.

小开

Try this one. This worked for me. With the Java Formatter (Windows > Preferences > Java > Code Style > Formatter), you can create a new Formatter profile from existing and then edit it.

If Eclipse doesn't allow to save this then create a new one and save in that.