Describes what comment types Jalopy recognizes and how they are treated.

As far as Jalopy is concerned, there are five types of comments:

Single-line comments

An end-of-line comment: all text from the ASCII characters "//" to the end of the line

// [PENDING] this should be part of the ErrorManager

Single-line comments are normally printed as-is but may be reformatted according to the code convention settings.

Multi-line comments

A traditional comment: all text from the ASCII characters "/*" to the ASCII characters "*/"

/*
public int getSubregionStartOffset(int line, int subregion)
{
    ChunkCache.LineInfo[] lineInfos = cache.getLineInfosForPhysicalLine(line);
    return buffer.getLineStartOffset(lineInfos[subregion].physicalLine)
        + lineInfos[subregion].offset;
}
*/

Multi-line comments are normally printed as-is but may be reformatted according to the code convention settings (see the section called "Format" below).

Javadoc comments

A documentation comment: actually a special kind of multi-line comment as defined by the Sun Javadoc specification; all text from the ASCII characters "/**" to the ASCII characters "*/"

/**
 * A scroll listener will be notified when the text area is scrolled, either
 * horizontally or vertically.
 */

Javadoc comments are normally printed as-is but may be reformatted according to the code convention settings.

Separator comments

A Jalopy-specific separator comment: actually a special kind of single-line comment; all text from the ASCII characters "//~" to the end of the line

//~ Inner classes ---------------------------------------

Separator comments are always removed during parsing and may be re-inserted during printing according to the code convention settings.

Refer to the section called "Comments" for more information about separator comments.

Pragma comments //J[directive]

A Jalopy-specific control comment: actually a special kind of single-line comment; all text from the ASCII characters "//J" to the end of the line

Currently, Jalopy recognizes three pragma comments: //J- and //J+ and //JDOC-

Pragma comment should always be placed in a line of its own! Never use them as trailing comments.

//J- and //J+

With these comments you can disable formatting for certain code sections. //J- tells Jalopy to disable formatting until //J+ will enable it again, all code between (and including) the two comments will be left as-is. Note that these comments can only be used in conjunction!

//J-
    if {condition()) return value;
//J+

//JDOC-

When placed in front of a Javadoc comment, disables the Javadoc generation feature, no matter what the code convention dictates.

    /**
     * DOCUMENT ME!
     */
    public class Test {

        //JDOC-
        public void test(String input) {

            ...
        }
    }

Pragma comments are always printed as-is.