Controls how Jalopy handles comments in source files.
Describes what comments 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
Single-line comments are normally printed as-is, but can be formatted as well (see Section 2.8.13.4, “Format”).
Multi-line comments
A traditional comment: all text from the ASCII characters
/* to the ASCII characters */
Example 2.760. Multi-line comment
/*
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 can be formatted as well (see Section 2.8.13.4, “Format”).
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 */.
Example 2.761. Javadoc comment
/**
* A scroll listener will be notified when the text area is scrolled, either
* horizontally or vertically.
*/
Javadoc comments are normally printed as-is, but can be formatted according to the code convention settings (see Section 2.8.14.1, “Format”).
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.
Separator comments are always removed during parsing and may be re-inserted during emitting according to the code convention settings. Refer to Section 2.8.11.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. Pragma comments are always printed
as-is. Currently, Jalopy supports the following pragma comments:
//J- and //J+
Lets you selectively 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
printed as-is.
Example 2.763. Pragma comments
//J- if (operator.equals("EQ")) return (left == right); else if (operator.equals("NE")) return (left != right); else if (operator.equals("LT")) return (left < right); else if (operator.equals("GT")) return (left > right); else if (operator.equals("LE")) return (left <= right); else if (operator.equals("GE")) return (left >= right); else { throw new IllegalArgumentException("Unknown int if operator: " + operator); } //J+
The two comments must always be used in conjunction and they must always appear on a line by themselves. Never place them after code elements!
//JDOC-
When placed in front of a Javadoc comment, disables the Javadoc generation feature no matter what the code convention dictates.
Example 2.764. //JDOC- comment
/** * DOCUMENT ME! */ public class Test { //JDOC- public void test(String input) { ... } }
//J:KEEP+
Instructs Jalopy to keep existing line breaks within array initializers and parameter or argument lists. The comment must be placed either directly after the left curly brace of array initializers, or the left parenthesis of parameter or argument lists, or the first element of the initializer or list.
Since 1.9.3
Example 2.765. Keep line breaks within call argument list
FormLayout layout = new FormLayout( //J:KEEP+ "fill:d:grow(1.0), 15px", "7px, d, 7px, fill:d:grow(1.0)");
Example 2.766. Keep line breaks within array initializer
String[] options =
{ //J:KEEP+
"-jar", aLauncher.getAbsolutePath(),
"-application", "org.foo.application.Main",
"-debug",
"-consolelog"
};
Please refer to the documentation of the wrapping options in Section 2.8.7.1.2, “Keep line breaks”, for information on how to configure the general wrapping behavior.
Jalopy associates comments using an assignment heuristics considering empty lines and/or column offsets. If you plan to switch between several code conventions on a regular basis, e.g. to toggle between personal preference and company guidelines, you should make sure to use similar separation settings in order to avoid any association differences. It is good practice to always craft a code convention that reflects the personal style from a master code convention (usually the company code convention) and only adjust those settings that run counter to personal taste. Please refer to the Profiles section for more information.
Controls whether and what types of comments should be removed during formatting.
Single-line comments
When 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).
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. 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.8.13.3.1, “Regular expression tester” for more information.
Multi-line comments
When 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).
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. 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.8.13.3.1, “Regular expression tester” for more information.
Javadoc comments
When 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).
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. 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.8.13.3.1, “Regular expression tester” for more information.
The regular expression tester lets you interactively craft a valid regular expression that contains a certain test string.
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. Jalopy uses Java’s build-in regular expression engine which is roughly equivalent with Perl 5 regular expressions. The syntax is explained here: http://java.sun.com/javase/6/docs/api/java/util/regex/Pattern.html. For a more precise description of the behavior of regular expression constructs consult Mastering Regular Expressions [Friedl97].
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.
Otherwise a red-colored message is displayed, and you may want to change your pattern and/or test string and restart the procedure.
When you are done 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
Example 2.768. Single-line comment (reformatted)
// 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.
Please note that as of Jalopy 1.6 you can disable formatting of individual
comments using the special /*- delimiter.
Example 2.771. Multi-line comment that keeps its style
/*- 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
Example 2.773. A long single-line comment that was wrapped
| // 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
Example 2.774. Wrapped single-line comments
// 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.
Example 2.775. Reflowed single-line comments
// 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
Example 2.776. A long multi-line comment
| /* A multi-line comment that spans multiple lines but exceeds the max. * line length | */ | |
Example 2.777. A long multi-line comment that was wrapped
| /* 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.
Reflow
Works similar to single-line comments (see Reflow single-line comments).
Since 1.0.3
Example 2.779. A long multi-line comment that was reflowed
| /* A multi-line comment that| * spans multiple lines but | * exceeds the max. line | * length | */ | |
Compare this to the result of Example 2.777, “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. This option is only available with either “Wrap single-line comments” or “Wrap multi-line comments” enabled. Please note that this setting only covers non-Javadoc comments. Javadoc comments are controlled independently, see “Javadoc line length”.
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.780. Insufficient space, wrapping impossible
| | | System.out.println("Hello");|// quite a long endline comment that |// appears after the statement | | | | O M
In the above example the space between the current column offset [O] and the maximal line length [M] is smaller than the specified minimal width (space between [O] and [S]), therefore wrapping is not possible.
Example 2.781. Sufficient space, wrapping possible
| | | System.out.println("Hello");|// quite a long endline | | |// comment that appears after | |// the statement | | | | | O S
In the above example the space between the current column offset [O] and the maximal line length [M] is greater than the specified minimal width (space between [O] and [S]), therefore wrapping is performed.
Lets you control miscellaneous comment options.
Keep first column comments as-is
When enabled, first column comments are never formatted and/or wrapped. As the name implies, first column comments are those comments that start at column one. They are typically used for commenting out blocks of code during development—something you might not want to be changed by a formatter.
Since 1.6
Example 2.782. First column comment
// System.out.println("appendingRemainingName: " + name.toString()); // Exception e = new Exception(); // e.printStackTrace();
Example 2.783. Wrapped first column comment
// 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
Example 2.784. Comments after left curly braces
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(); } }
When the option is enabled, the example above would be printed as:
Example 2.785. Comments after left curly braces
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 the if statement is affected. The comment before the if statement and the consecutive comments after the else statement have been left untouched.