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 Section 2.6.8.4, "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 Section 2.6.6.3, "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.

Jalopy associates comments using an assignment heuristics considering empty lines and column offsets (as sketched below).

Controls whether and what types of comments should be removed during the formatting process.

Single-line comments

If enabled, removes all single-line comments found in a source file that matches certain criteria.

To customize what single-line comments should be removed, you can use the Customize... button to specify the desired behavior (since 1.1).

Figure 2.62. Configure single-line comment removal

You can choose whether all single-comments should be removed or specify a regular expression (regex) to match only certain comments. Note that the regex defines a pattern that is contained in a comment - it must not match exactly.

You can either enter the regex directly into the provided text field or craft one with the help of a little tool that lets you interactively test the validity of your regex. You can invoke the regex helper via the Change... button. Note that the Remove custom radio box must be selected in order to be able to change the regex.

Please note that the specified regular expression is only matched against the contents of comments, not any surrounding code elements!

The regex helper is explained in detail below, see Section 2.6.8.3.1, "Regular expression tester" for more information.

Multi-line comments

If enabled, removes all multi-line comments (sometimes called block comments) found in a source file that matches certain criteria.

To customize what multi-line comments should be removed, you can use the Customize... button to specify the desired behavior (since 1.1).

Figure 2.63. Configure multi-line comment removal

You can choose whether all multi-comments should be removed or specify a regular expression (regex) to match only certain comments. Note that the regex defines a pattern that is contained in a comment, it must not match exactly.

You can either enter the regex directly into the provided text field or craft one with the help of a little tool that lets you interactively test the validity of your regex. You can invoke the regex dialog via the Change... button. Note that the Remove custom radio box must be selected in order to be able to change the regex.

Please note that the specified regular expression is only matched against the contents of comments, not any surrounding code elements!

The regex tester is explained in detail below, see Section 2.6.8.3.1, "Regular expression tester" for more information.

Javadoc comments

If enabled, removes all Javadoc comments found in a source file that matches certain criteria. This may prove useful in conjunction with the Javadoc auto-generation capabilities to build Javadoc from scratch.

To customize what Javadoc comments should be removed, you can use the Customize... button to specify the desired behavior (since 1.1).

Figure 2.64. Configure Javadoc comment removal

You can choose whether all single-comments should be removed or specify a regular expression (regex) to match only certain comments. Note that the regex defines a pattern that is contained in a comment, it must not match exactly.

You can either enter the regex directly into the provided text field or craft one with the help of a little tool that lets you interactively test the validity of your regex. You can invoke the regex dialog via the Change... button. Note that the Remove custom radio box must be selected in order to be able to change the regex.

Please note that the specified regular expression is only matched against the contents of comments, not any surrounding code elements!

The regex tester is explained in detail below, see Section 2.6.8.3.1, "Regular expression tester" for more information.

2.6.8.3.1. Regular expression tester

The regular expression tester lets you interactively craft a valid regular expression that contains a certain test string.

Figure 2.65. Regular expression tester

Regex

The Regex text field is where you have to insert the regular expression. This text field initially contains the current pattern for the comment type that is under construction.

The used regular expression syntax is that of Perl 5.003. See Mastering Regular Expressions [Friedl97] for an in-depth look at this regular expression flavor.

String

The String text field is where you have to enter a string that should be matched by the specified regular expression. This text field is initially empty.

Once you have edited the two text fields you may want to use the Test button to perform a pattern matching test in order to make sure that the specified pattern matches as desired.

If testing is successful, a green-colored message appears, to indicate that fact.

Figure 2.66. Successful regex test

Otherwise a red-colored message is displayed, and you may want to change your pattern and/or test string and restart the procedure.

Figure 2.67. Failed regex test

If you are finished editing the regular expression, you can press the Apply button to take over (note that you are not required to perform any testing, the regex is accepted even when invalid!).

You can always use the Cancel button to cancel editing at any time. The dialog will be closed and no changes applied.

Controls the reformatting of comments.

Single-line comments

Enables the reformatting of single-line comments. Only affects the space between leading delimiter and comment text as shown in the examples below.

Since 1.0.3

//Sometimes people run
//the comments against the delimiters

// Sometimes people run
// the comments against the delimiters

Multi-line comments

Enables the reformatting of multi-line comments. Only affects the leading asterixes of consecutive comment lines as shown in the examples below.

/* Multi-line
* comment.
* end.
*/

/* Multi-line
 * comment.
 * end.
 */

Please note that as of Jalopy 1.6 you can disable formatting of individual comments using the special /*- delimiter.

/*- Comment that
* should NOT
* be formatted
*/

Controls the wrapping behavior of comments.

Single-line comments

When enabled, Jalopy tries to ensure that single-line comments do not exceed the maximal line length.

Since 1.0.3

                            |
// this is a long comment so I would like it to wrap
                            |

                            |
// this is a long comment so|
// I would like it to wrap  |
                            |

Reflow

By default, wrapping happens on a line-by-line basis, i.e. every line that would exceed the maximal length will be split and the resulting chunks will be each printed on a line of its own. To put it in another way: all existing line breaks are kept.

This is no problem with a single comment, but when there are multiple comments in row, wrapping may leave annoying artifacts like in the example below.

Since 1.0.3

// when comments are reflowed (both single and multi-line), empty  |
// comment lines are kept to allow some                            |
// sort of control how things are broke up                         |
//                                                                 |
// otherwise it might be very dangerous to use this feature.       |
// The choice is yours                                             |

A better strategy might be to ignore existing line breaks and have the comments reflowed.

// when comments are reflowed (both single and multi-line), empty  |
// comment lines are kept to allow some sort of control how things |
// are broke up                                                    |
//                                                                 |
// otherwise it might be very dangerous to use this feature. The   |
// choice is yours                                                 |

Please note that existing blank lines are always kept!

Multi-line comments

When enabled, ensures that multi-line comments do not exceed the maximal line length.

Since 1.0.3

                            |
/* A multi-line comment that spans multiple lines but exceeds the max.
 * line length              |
 */                         |
                            |

                            |
/* A multi-line comment that|
 * spans multiple lines but |
 * exceeds the max.         |
 * line length              |
 */                         |
                            |

Please note that as of Jalopy 1.6 you can disable wrapping of individual comments using the special /*- delimiter.

/*- Comment that
* should NOT
* be wrapped
*/

Reflow

Works similar to single-line comments (see Reflow single-line comments).

Since 1.0.3

                            |
/* A multi-line comment that|
 * spans multiple lines but |
 * exceeds the max. line    |
 * length                   |
 */                         |
                            |

Compare this to the result of Example 2.744, "A long multi-line comment that was wrapped" and see how the last two lines differ.

Wrap comments when line length greater than

Lets you define the maximal column width that comments are allowed to use. Jalopy keeps the comments within this range.

Please note that this setting only covers non-Javadoc comments. Javadoc comments are controlled independently, see "Javadoc line length".

This option is only available with either "Wrap single-line comments" or "Wrap multi-line comments" enabled.

Since 1.6

Only wrap when space greater than

Lets you define the minimal amount of horizontal space that is required to let wrapping occur. This is the space between the current line offset and the maximal line length as defined above (see "Comment Line Length").

If the difference between these two boundaries is greater than the specified lower bound, wrapping occurs. In contrast, if the difference between current offset and maximal line length is smaller or equal to the specified lower bound, no wrapping will occur.

Please note that this option is only available with either "Wrap single-line comments" or "Wrap multi-line comments" enabled.

Since 1.0.3

Example 2.747. Insufficient space, wrapping impossible

In the above example the space between the current column offset (blue line) and the maximal line length (red line) is smaller than the specified minimal width (space between red and green line), therefore wrapping is not possible.

Example 2.748. Sufficient space, wrapping possible

In the above example the space between the current column offset (blue line) and the maximal line length (red line) is greater than the specified minimal width (space between red and green line), therefore wrapping is possible.

Lets you control miscellaneous comment options.

Keep first column comments as-is

When enabled, first column comments are never formatted and/or wrapped. First column comments are often used for commenting out blocks of code during development and formatting/wrapping might severely come into the way here.

Since 1.6

// System.out.println("appendingRemainingName: " + name.toString()); Exception 
// e = new Exception(); e.printStackTrace();

// System.out.println("appendingRemainingName: " + name.toString());
// Exception e = new Exception();
// e.printStackTrace();

Move comments after brace block

When enabled, single comments that appear in the first line after the left curly brace of a statement block and only cover one line are moved right after the brace. This way you can achieve a more dense layout in case you want to save vertical space.

Since 1.7

When enabled, the following code

void test()
{
    /**
     * @todo evaluate whether this is still necessary
     */
    if (condition1)
    {
        // i should do something
        doSomething();
    }
    else if (condition2)
    {
        // [PENDING] this should be part of whatever, ask Jeff
        // what to do
        takeAction();
    }
}

would be printed as:

void test()
{
    /**
     * @todo evaluate whether this is still necessary
     */
    if (condition1)
    { // i should do something
        doSomething();
    }
    else if (condition2)
    {
        // [PENDING] this should be part of whatever, ask Jeff
        // what to do
        takeAction();
    }
}

Please note how only the single comment within after the if statement is affected. The comment after the declaration block brace and the consecutive comments after the else statement, have been left alone.