Making Eclipse's Java code formatter ignore block comments

Solution 1:

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

Solution 2:

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 <dl>, <dt> and <dd> will help to present it properly within the Javadoc view.

Solution 3:

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.

Solution 4:

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 :)