Provides option to control the behavior of the description section of a Javadoc comments.

The description begins after the starting delimiter /** and continues until the tag section. The tag section starts with the first block tag, which is defined by the first @ character that begins a line (ignoring leading asterisks, white space and comment separator). The main description cannot continue after the tag section begins.

/**
 * This sentence would hold the main description for this doc comment.
 * @see java.lang.Object
 */

Correct description section

When enabled, Jalopy inserts a missing description into existing Javadoc comments. Unlike specified otherwise (see "Use text from @return" below), the description is taken from the template for the code element that contains the Javadoc comment. Refer to the section called "Templates" for information on how to customize the templates.

Since 1.2.1

Only when generation

Only inserts the missing description when Javadoc auto-generation has been enabled for the declaration element that contains the Javadoc comment.

Since 1.2.1

/**
 * @jalopy.group accessor
 */
protected int getFoo () {
    ...
}

/**
 * DOCME!
 *
 * @jalopy.group accessor
 */
protected int getFoo () {
    ...
}

Only when @param or @return

Only inserts the missing description when a @param or @return block tag can be found in the Javadoc comment.

Since 1.2.1

/**
 * @jalopy.group accessor
 */
protected int getFoo () {
    ...
}

/**
 * @jalopy.group  accessor
 */
protected int getFoo () {
    ...
}

/**
 * @return        returns the foo property.
 * @jalopy.group  accessor
 */
protected int getFoo () {
    ...
}

/**
 * DOCME!
 *
 * @return        returns the foo property.
 *
 * @jalopy.group  accessor
 */
protected int getFoo () {
    ...
}

Only when no @see

Only inserts the missing description when no @see block tag can be found in the Javadoc comment. The default behavior is to disable the insertion of a missing description if the comment only consists of a single @see block tag or starts with an {@inheritDoc} in-line tag.

In order to avoid adding information that is redundant, one may enable this switch when @see tags are used to point to related documentation.

Since 1.2.1

/**
 * @jalopy.group accessor
 */
protected int getFoo () {
    ...
}

/**
 * DOCME!
 *
 * @jalopy.group  accessor
 */
protected int getFoo () {
    ...
}

/**
 * @jalopy.group  accessor
 * @see           #com.foo.OtherClass
 */
protected int getFoo () {
    ...
}

/**
 * @jalopy.group  accessor
 * @see           #com.foo.OtherClass 
 */
protected int getFoo () {
    ...
}

Use text from @return

When enabled, the description text of the @return tag is used (when present) for a missing description. The first letter of the text will upper-cased.

Since 1.5

/**
 * @return  returns the result of the operation.
 */
public Object getResult() {
    ...
}

/**
 * TODO: DOCME!
 * 
 * @return  returns the result of the operation.
 */
public Object getResult() {
    ...
}

/**
 * Returns the result of the operation.
 * 
 * @return  returns the result of the operation.
 */
public Object getResult() {
    ...
}

Provides options to control the behavior for the block tags of Javadoc commnets.

The description begins after the starting delimiter /** and continues until the tag section. The tag section starts with the first block tag, which is defined by the first @ character that begins a line (ignoring leading asterisks, white space and comment separator). The main description cannot continue after the tag section begins. There can be any number of tags - some types of tags can be repeated while others cannot. In the following example, the @see tags starts the tag section:

/**
 * This sentence would hold the main description for this doc comment.
 * @see java.lang.Object
 */

Correct tag section

When enabled, missing Javadoc block tags will be inserted, obsolete tags can be removed. Spelling errors of block and in-line tags are corrected.

The description of a tag is taken from the template for the code element that contains the Javadoc comment. Refer to the section called "Templates" for information on how to customize the templates.

Only when generation

Only corrects tags when Javadoc auto-generation has been enabled for the declaration element that contains the Javadoc comment.

Since 1.2.1

/**
 * @jalopy.group accessor
 */
protected int getFoo () {
    ...
}

/**
 * @return       DOCME!
 *
 * @jalopy.group accessor
 */
protected int getFoo () {
    ...
}

Only when @param or @return

Only corrects tags when a @param or @return block tag can be found in the Javadoc comment.

Since 1.2.1

/**
 * @jalopy.group  accessor
 */
protected int getFoo (int param) {
    ...
}

/**
 * @jalopy.group  accessor
 */
protected int getFoo (int param) {
    ...
}

/**
 * @param         param  a parameter
 * @jalopy.group  accessor
 */
protected int getFoo (int param) {
    ...
}

/**
 * @param         param  a parameter
 *
 * @return        returns  the foo property.
 *
 * @jalopy.group  accessor
 */
protected int getFoo (int param) {
    ...
}

Only when no @see

Disables the auto-correction when a @see tag is found in the comment. The default behavior is to disable auto-correction if the comment only consists of a single @see block tag or starts with an {@inheritDoc} in-line tag.

In order to avoid adding information that is redundant, one may enable this switch when @see tags are used to point to related documentation.

Since 1.0.1

Misspelled tag names

When enabled, misspelled Javadoc tag names will be corrected when possible.

When Jalopy encounters an invalid tag name, i.e. the name is not part of the list with valid tag names, it determines wether the tag name is vastly similar with one on the list. If so, Jalopy will pick the one from the list otherwise it reports an error.

For information about the build-in list with valid Javadoc tag names refer to the section called "Block tags", the section called "In-line tags" and Appendix B, Build-in XDoclet tags.

Since 1.3

Add @throws tags

When enabled, performs an additional check for exceptions that are actually thrown from within a constructor or method body, but not documented and adds block tags. E.g. if a method only declares to throw an IOException, but actually throws a FileNotFoundException, and this FileNotFoundException has not been documented with a @throws tag, it will be added.

/**
 * Description
 *
 * @param   rFile  input file.
 *
 * @throws  IOException if an I/O problem occured.
 */
public void sample(File rFile) throws IOException {
    if (rFile.exists())
        throw new FileNotFoundException();

    ...
}

/**
 * Description
 *
 * @param   rFile  input file.
 *
 * @throws  IOException            if an I/O problem occured.
 * @throws  FileNotFoundException  DOCUMENT ME!
 */
public void sample(File rFile) {
    if (rFile.exists())
        throw new FileNotFoundException();

    ...
}

Ignore runtime exceptions

When enabled, no tags will be added or removed for runtime exceptions and errors that are thrown from within a method or constructor body.

Please note that enabling this option will cause present @throws tags that document runtime exceptions or errors to be removed! If you want to keep existing tags, please enable the "Keep @throws tags" option as well.

You have to explicitly enable type repository services for the Ant, Console and Maven Plug-ins to activate this feature! Please refer to the documentation of the individual Plug-ins to learn how one can accomplish this (see Part II, "Plug-ins").

Since 1.0

/**
 * Description
 *
 * @throws  IllegalArgumentException  DOCME!
 */
public void isNewline(int offset) {
    if (input <= 1) throw new IllegalArgumentException();
    ..
}

/**
 * Description
 */
public void isNewline(int offset) {
    if (input <= 1) throw new IllegalArgumentException();
    ..
}

Keep @throws tags

When enabled, no existing @throws tags are removed from comments. This feature proves useful if you have comments with existing @throws tags for runtime exceptions that are not actually thrown from within a method body.

Since 1.0

Add template tags

When enabled, tags that are defined in the Javadoc template but missing in the Javadoc comment of the corresponding declaration node are inserted.

Missing tags are only inserted when their declaration has its Javadoc generation option enabled for the current scope. This holds true if even when the Javadoc comment generation is disabled globally in order to allow fine grained control when and for what declartions missing tags should be inserted. Please refer to Enable Javadoc generation for for information on how to enable Javadoc generation for specific declarations.

For information on how to customize the Javadoc templates, please refer to the section called "Templates".

Since 1.5

Say you have defined your class template to look like this:

/**
 * TODO: DOCME!
 *
 * @author $user.name$
 */

Upon reformatting, Jalopy ensures that all existing class level Javadoc comments contain the @author tag. Thus, the following comment

/**
 * Encapsulate an attribute declaration.
 */
class AttributeDecl {
}

could become

/**
 * Encapsulate an attribute declaration.
 *
 * @author  John Doo
 */
class AttributeDecl {
}

Note how the $user.name variable expression is interpolated during formatting! Environment variables are discussed in the section called "Environment".

Missing tags are added at the end of the tag section in the order they are defined in the template. We recommend to enable Tag sorting in order to ensure a specific ordering.

Add method type parameter tags

When enabled, Jalopy enforces/corrects @param tags for generic method and constructor declarations.

/**
 * blah.
 *
 * @param  string  blah
 *
 * @return  blah
 */
<T, V extends T> V convert(String string);

will have tags inserted for the type parameters.

Since 1.6

/**
 * blah.
 *
 * @param  <T>  blah
 * @param  <V>  blah
 * @param  string     blah
 *
 * @return  blah
 */
<T, V extends T> V convert(String string);

Please note that existing @param tags documenting type parameters will be removed when this option is disabled!

Remove misused tags

When enabled, the validity of block tags will be checked. Not all tags can be used in all contexts. Tags that are invalid will be removed. If left disabled, Jalopy only prints warnings about misused tags.

Since 1.0

Use description for @return

When enabled, the text for a missing @return tag description is not taken from the template, but the first sentence of description section is taken (when present). The first letter of the description will be lower-cased.

Since 1.5

/**
 * Returns the result of the calculation.
 */
public Object getResult() {
   ...
}

/**
 * Returns the result of the calculation.
 *
 * @return  DOCME!
 */
public Object getResult() {
   ...
}

/**
 * Returns the result of the calculation.
 *
 * @return returns the result of the calculation.
 */
public Object getResult() {
   ...
}

Add missing description

When enabled, missing descriptions of certain Javadoc block tags will be tagged with a marker. The tag marker is inserted for the following tags: @author, @deprecated, @exception, @param, @return, @see, @serialData, @serialField, @since, @throws, @version.

The marker text is taken from the description section of corresponding template.

XDoclet or custom tags will remain untouched.

Since 1.5

/*
 * HTML is the top level element
 *
 * @param lexer
 *
 * @return
 */
public static Node parseDocument(Lexer lexer) {}

When the option is left disabled, the above example would become

/**
 * HTML is the top level element
 *
 * @param   lexer
 *
 * @return
 */
public static Node parseDocument(Lexer lexer) {}

But when the option is enabled, the result would be

/**
 * HTML is the top level element
 *
 * @param   lexer  DOCME!
 *
 * @return  DOCME!
 */
public static Node parseDocument(Lexer lexer) {}