[Skip to content]

2.8.14. Javadoc

Lets you control all Javadoc-related options. Javadoc is a tool that parses the declarations and documentation comments in a set of Java source files and produces a corresponding set of HTML pages describing the public API or implementation documentation. Jalopy includes functionality to generate and maintain such comments automatically.

2.8.14.1. Format

Lets you control the Javadoc formatting options.

Figure 2.69. Javadoc settings page

Javadoc settings page

2.8.14.1.1. Format comments

Enables or disables the formatting of Javadoc comments. When enabled, Javadoc comments are always formatted according to the options specified below.

Note

The formatting style of leading and closing comment delimiter and leading asterisk characters are determined by analyzing the templates defined for the different declaration elements. Please refer to Section 2.8.14.5, “Templates” for more information about Javadoc templates

2.8.14.1.2. Block tags

Lets you control the handling of Javadoc block tags.

Indent description

When enabled, the description of a Javadoc block tag is indented/aligned beyond the tag name or tag parameter upon line wrapping. Otherwise successive description lines will start at the same column offset with the tag.

Since 1.6

Example 2.786. Indented tag descriptions

/**
 * This is overridden to return false if the current <code>Icon</code>'s
 * <code>Image</code> is not equal to the passed in <code>Image</code>
 * <code>img</code>.
 *
 * @see  java.awt.image.ImageObserver
 * @see  java.awt.Component#imageUpdate(java.awt.Image, int, int, int,
 *       int, int)
 *
 * @param  img  the <code>Image</code> to be compared
 * @param  infoflags  flags used to repaint the button when the image is
 *                    updated and which determine how much is to be
 *                    painted
 * @param  x  the x coordinate
 */

Example 2.787. Unindented tag descriptions

/**
 * This is overridden to return false if the current <code>Icon</code>'s
 * <code>Image</code> is not equal to the passed in <code>Image</code>
 * <code>img</code>.
 *
 * @see  java.awt.image.ImageObserver
 * @see  java.awt.Component#imageUpdate(java.awt.Image, int, int, int,
 * int, int)
 *
 * @param  img  the <code>Image</code> to be compared
 * @param  infoflags  flags used to repaint the button when the image is
 * updated and which determine how much is to be painted
 * @param  x  the x coordinate
 */

Group equal

When enabled, sections with equal tags are separated by a single blank line.

Since 1.0

Example 2.788. Javadoc without grouped tags

/**
 * Returns the next list element that starts with a prefix.
 *
 * @param      prefix      the string to test for a match
 * @param      startIndex  the index for starting the search
 * @param      bias        the search direction, either Position.Bias.
 *                         Forward or Position.Bias.Backward.
 * @return     the index of the next list element that starts with the
 *             prefix; otherwise -1
 * @exception  IllegalArgumentException  if prefix is null or startIndex is
 *                                       out of bounds
 * @since      1.4
 */

Example 2.789. Javadoc with grouped tags

/**
 * Returns the next list element that starts with a prefix.
 *
 * @param      prefix      the string to test for a match
 * @param      startIndex  the index for starting the search
 * @param      bias        the search direction, either Position.Bias.
 *                         Forward or Position.Bias.Backward.
 *
 * @return     the index of the next list element that starts with the
 *             prefix; otherwise -1
 *
 * @exception  IllegalArgumentException  if prefix is null or startIndex is
 *                                       out of bounds
 *
 * @since      1.4
 */

Align name/description

When enabled, the names and/or descriptions of tags are aligned in a table like manner to enhance readability. Otherwise each tag description is indented on its own. You need to have the indentation of descriptions enabled to see descriptions aligned.

Since 1.0

Example 2.790. Javadoc without aligned tags

/**
 * Returns the next list element that starts with a prefix.
 *
 * @param  prefix  the string to test for a match
 * @param  startIndex  the index for starting the search
 * @param  bias  the search direction, either Position.Bias.Forward or
 *               Position. Bias.Backward.
 * @return  the index of the next list element that starts with the prefix;
 *          otherwise -1
 * @exception  IllegalArgumentException  if prefix is null or startIndex is
 *                                       out of bounds
 * @since  1.4
 */

Example 2.791. Javadoc with aligned tags

/**
 * Returns the next list element that starts with a prefix.
 *
 * @param      prefix      the string to test for a match
 * @param      startIndex  the index for starting the search
 * @param      bias        the search direction, either Position.Bias.
 *                         Forward or Position.Bias.Backward.
 * @return     the index of the next list element that starts with the
 *             prefix; otherwise -1
 * @exception  IllegalArgumentException  if prefix is null or startIndex is
 *                                       out of bounds
 * @since      1.4
 */

Align attributes

When enabled, all attributes of tags with multiple attributes are indented to the level of the first '.' character in the name of the tag. Otherwise all attributes are indented by two spaces.

Since 1.0.1

Example 2.792. Javadoc with standard indented tag attributes

/**
 * @ejb.resource-ref
 *   res-auth     = "Container"
 *   res-ref-name = "${kirus.resource.database.name}"
 *   res-type     = "javax.sql.DataSource"
 */

Example 2.793. Javadoc with aligned tag attributes

/**
 * @ejb.resource-ref
 *      res-auth     = "Container"
 *      res-ref-name = "${kirus.resource.database.name}"
 *      res-type     = "javax.sql.DataSource"
 */

Sort block tags

When enabled, block tags are sorted. By default, the order is as recommended by the Javadoc creators (see http://java.sun.com/j2se/javadoc/writingdoccomments/ for more information), but you can configure the order manually yourself (see below). When disabled, block tags are printed in their original order.

Since 1.0

Sort attributes

When enabled, if a block tag contains multiple attributes, these are sorted by name. Otherwise the attributes are printed in their original order.

Since 1.0

Example 2.794. Unsorted XDoclet tag attributes

/**
 * Sets the model that represents the contents or “value” of the list and
 * clears the list selection after notifying <code>
 * PropertyChangeListeners</code>.<p> This is a JavaBeans bound property.
 *
 * @param      model  the <code>ListModel</code> that provides the list of
 *                    items for display
 *
 * @beaninfo
 *         bound: true
 *     attribute: visualUpdate true
 *   description: The object that contains the data to be drawn
 */

Example 2.795. Sorted XDoclet tags

/**
 * Sets the model that represents the contents or “value” of the list and
 * clears the list selection after notifying <code>
 * PropertyChangeListeners</code>.<p> This is a JavaBeans bound property.
 *
 * @param      model  the <code>ListModel</code> that provides the list of
 *                    items for display
 *
 * @beaninfo
 *     attribute: visualUpdate true
 *         bound: true
 *   description: The object that contains the data to be drawn
 */

Sort XDoclet tags

When enabled, XDoclet block tags are sorted by name. Otherwise the order is not changed. Please note that this option requires “Sort block tags” to be enabled.

Since 1.9.1

Example 2.796. Unsorted XDoclet tags

/**
 * @ejb.home
 *   extends       = "javax.ejb.EJBHome"
 *   local-extends = "javax.ejb.EJBLocalHome"
 * @ejb.interface
 *   extends       = "javax.ejb.EJBObject"
 *   local-extends = "javax.ejb.EJBLocalObject"
 *
 * @weblogic.transaction-descriptor
 *   trans-timeout-seconds = "122"
 * @weblogic.transaction-isolation
 *   TRANSACTION_READ_COMMITTED
 *
 * @ejb.transaction
 *   type = "RequiresNew"
 *
 * @weblogic.enable-call-by-reference
 *   True
 *
 * @ejb.resource-ref
 *   res-ref-name = "jdbc/foo-pool"
 *   res-type     = "javax.sql.DataSource"
 *   res-auth     = "Container"
 */

Example 2.797. Sorted XDoclet tags

/**
 * @ejb.home
 *   extends       = "javax.ejb.EJBHome"
 *   local-extends = "javax.ejb.EJBLocalHome"
 * @ejb.interface
 *   extends       = "javax.ejb.EJBObject"
 *   local-extends = "javax.ejb.EJBLocalObject"
 * @ejb.resource-ref
 *   res-ref-name = "jdbc/foo-pool"
 *   res-type     = "javax.sql.DataSource"
 *   res-auth     = "Container"
 * @ejb.transaction
 *   type = "RequiresNew"
 *
 * @weblogic.enable-call-by-reference
 *   True
 * @weblogic.transaction-descriptor
 *   trans-timeout-seconds = "122"
 * @weblogic.transaction-isolation
 *   TRANSACTION_READ_COMMITTED
 */

Configure Tag Order...

Lets you configure the order of block tags when tag sorting is enabled. Pressing the button will display a configuration dialog that lets you specify both the order of block tags and a grouping section to define what tags should be separated.

Figure 2.70. Configure Javadoc tag order

Configure Javadoc tag order

Select an entry in the list and use the Up and Down buttons to configure the sort order. To adjust grouping, specify the grouping section each tag should be part of. “None” means that tags are always separated. Otherwise two consecutive tags are only separated if their grouping section is different.

Since 1.8

2.8.14.1.3. Compact elements

Javadoc start and end delimiters are usually printed on its own line. When the comment body does not contain much text, emitting everything in one line might be an easy way to save vertical space. Same with tags and attributes.

Class comments

Lets you specify how Javadoc comments of class, interface and annotation type declarations that fit into one line should be printed.

Since 1.5

Example 2.798. Class Javadoc comment

/**
 * A simple container for Foo data.
 */
public class Foo {
}

When enabled, Javadoc comments will be printed in a single line, when possible.

Example 2.799. Class Javadoc comment (shortened)

/** A simple container for Foo data. */
public class Foo {
}

Enum comments

Lets you specify how Javadoc comments of enum declarations that fit into one line should be printed.

Since 1.7

Example 2.800. Enum Javadoc comment

/**
 * The foo enumeration.
 */
enum Foo {
    ...
}

When enabled, Javadoc comments will be printed in a single line, when possible.

Example 2.801. Enum Javadoc comment (shortened)

/** The foo enumeration. */
enum Foo {
    ...
}

Field comments

Lets you specify how Javadoc comments of fields or enum constants, that fit into one line should be printed.

Example 2.802. Field Javadoc comment

/**
 * What history policy should be used?
 */
private History.Policy _historyPolicy = History.Policy.DISABLED;

When enabled, Javadoc comments for fields or enum constants will be printed in a single line, when possible.

Example 2.803. Field Javadoc comment (shortened)

/** What history policy should be used? */
private History.Policy _historyPolicy = History.Policy.DISABLED;

Method comments

When enabled, Javadoc comments for methods are printed in a single line when possible. This depends not only on the length of the description section, but also on your correction settings. If the auto-correction feature for the tag section is enabled, the comment is only printed in a single line, if the method does contain a void return type and no parameters (because otherwise Javadoc tags are inserted).

Since 1.3

Example 2.804. Methods

/**
 * Transfer all entries from src to dest tables
 */
private void transfer(Entry[] src, Entry[] dest) {
    ...
}

When enabled, Javadoc comments for methods and constructors will be printed in a single line, when possible.

Example 2.805. Method Javadoc comment (shortened)

/** Transfer all entries from src to dest tables */
private void transfer(Entry[] src, Entry[] dest) {
    ...
}

Single block tags

Lets you choose whether comments that only consists of a single block tag should be printed in one line when possible. Please note that enabling this option only affects those comments for which compacting has been enabled. E.g. if you want to compact fields with single block tags, you need to enable the "compact field comments" option.

Since 1.8

Example 2.806. Single block tag

/**
 * @see com.foo.MyClass
 */
class Demo{
}

Example 2.807. Single block tag compacted

/** @see com.foo.MyClass */
class Demo{
}

Single attributes

Lets you choose whether single attributes should be printed in just one line after the tag name when possible. Otherwise, a line break is printed after the tag name.

Since 1.9.1

Example 2.808. Single XDoclet attribute

/**
 * @weblogic.transaction-descriptor
 *   trans-timeout-seconds = "122"
 */
class Demo{
}

Example 2.809. Single XDoclet attribute compacted

/**
 * @weblogic.transaction-descriptor  trans-timeout-seconds = "122"
 */
class Demo{
}

Remove stars in <pre> tags

Lets you remove leading stars in pre-formatted sections. It is often tedious to manually maintain leading stars in front of code snippets enclosed with <pre> tags. They are ignored by Javadoc anyway. With this option you can control whether Jalopy should remove any leading stars in pre-formatted sections or have them printed.

Since 1.6

Example 2.810. Javadoc comment with preformatted section

/**
 * <p>As with <code>InputMap</code> if you create a cycle, eg:
 * <pre>
 *   ActionMap am = new ActionMap();
 *   ActionMap bm = new ActionMap():
 *   am.setParent(bm);
 *   bm.setParent(am);
 * </pre>
 * some of the methods will cause a StackOverflowError to be thrown.
 */

Example 2.811. Javadoc comment without leading stars in preformatted section

/**
 * <p>As with <code>InputMap</code> if you create a cycle, eg:
 * <pre>
     ActionMap am = new ActionMap();
     ActionMap bm = new ActionMap():
     am.setParent(bm);
     bm.setParent(am);
 * </pre>
 * some of the methods will cause a StackOverflowError to be thrown.
 */

Normalize white space

When enabled, all white space gaps are reduced to a single blank space (normalized). Otherwise Jalopy will left white space gaps after sentences alone.

Since 1.8

Example 2.812. White space gaps

/**
 * This is the first sentence.  This is the second sentence.  This is the
 * third sentence.  This is the forth sentence.  This is the fifth
 * sentence.  Thissssssssssssssssss
 */

Example 2.813. Normalized white space

/**
 * This is the first sentence. This is the second sentence. This is the
 * third sentence. This is the forth sentence. This is the fifth sentence.
 * Thissssssssssssssssss
 */

Separate multi-line XDoclet tags

When enabled, a blank line is printed before and after XDoclet tags that require more than one line.

Since 1.9.1

Example 2.814. Javadoc XDoclet tags

/**
 * @ejb.home
 *   extends       = "javax.ejb.EJBHome"
 *   local-extends = "javax.ejb.EJBLocalHome"
 * @ejb.bean
 *   name         = "AboActionManager"
 *   type         = "Stateless"
 *   display-name = "FooManagerBean"
 *   description  = "FooManager EJB"
 *   view-type    = "all"
 *   jndi-name    = "FooMgr"
 * @ejb.interface extends = "javax.ejb.EJBObject"
 */ 

Example 2.815. Separated Javadoc XDoclet tags

/**
 * @ejb.home
 *   extends       = "javax.ejb.EJBHome"
 *   local-extends = "javax.ejb.EJBLocalHome"
 *
 * @ejb.bean
 *   name         = "AboActionManager"
 *   type         = "Stateless"
 *   display-name = "FooManagerBean"
 *   description  = "FooManager EJB"
 *   view-type    = "all"
 *   jndi-name    = "FooMgr"
 *
 * @ejb.interface extends = "javax.ejb.EJBObject"
 */ 

2.8.14.2. Line Wrapping

2.8.14.2.1. Wrapping

Lets you control the wrapping options for Javadoc comments.

Line length

Lets you define the maximal column width that Javadoc comments are allowed to use. Jalopy tries to keep the comments within this range upon reformatting.

Since 1.0

Disable wrapping for in-line tags

Lets you disable automatic line wrapping for in-line tags. Please note that this means that in-line tags will always print in just one line. If the tag would exceed the maximal line length, a line break is inserted before the tag. But please be aware that the maximal line length could still be exceeded when the tag does not fit in a whole line!

Since 1.5

Example 2.816. Wrapped Javadoc in-line tag

/**                                                               |
 * This is overridden to return false if the {@link java.awt.Icon |
 * Icon’s} Image is not equal to the passed in Image.             |
 */                                                               |

Example 2.817. Javadoc in-line tag (wrapping disabled)

/**                                                               |
 * This is overridden to return false if the                      |
 * {@link java.awt.Icon Icon’s} Image is not equal to the passed  |
 * in Image.                                                      |
 */                                                               |

2.8.14.2.2. Misc

Lets you control miscellaneous Javadoc settings.

Inner spacing

Lets you define the amount of white space that gets printed between block tags and their description text.

Since 1.0

Example 2.818. One space inner spacing

/**
 * Returns the next list element that starts with a prefix.
 *
 * @param     prefix     the string to test for a match
 * @param     startIndex the index for starting the search
 * @param     bias       the search direction, either Position.Bias.Forward
 *                       or Position.Bias.Backward.
 *
 * @return    the index of the next list element that starts with the prefix;
 *            otherwise -1
 *
 * @exception IllegalArgumentException if prefix is null or startIndex is out
 *                                     of bounds
 *           ^                        ^
 * @since     1.4
 */

Example 2.819. Two spaces inner spacing

/**
 * Returns the next list element that starts with a prefix.
 *
 * @param      prefix      the string to test for a match
 * @param      startIndex  the index for starting the search
 * @param      bias        the search direction, either Position.Bias.Forward
 *                         or Position.Bias.Backward.
 * @return     the index of the next list element that starts with the
 *             prefix; otherwise -1
 * @exception  IllegalArgumentException  if prefix is null or startIndex is
 *                                       out of bounds
 *           ^^                        ^^
 * @since      1.4
 */

Indent HTML tags

Enables the indentation of most HTML block tags (like lists, tables and the like). Please note that the HTML contents have to be well-formed for this feature to work! By default, Jalopy will inform you about invalid HTML when this feature was enabled. Another choice might be to enable the "Check HTML tags" feature to automatically ensure well-formed HTML (among other things, see below).

Since 1.0

2.8.14.3. Generation

Controls the auto-generation of missing Javadoc comments.

Figure 2.71. Javadoc settings page

Javadoc settings page

Please refer to Section 2.8.14.5, “Templates” for information about how to define templates that are used for Javadoc comment generation.

Generate Javadoc comments

Enables or disables the comment auto-generation as a whole.

Since 1.2.1

Include inner classes

Enables comment auto-generation for nested inner classes. Auto-generation does not apply to anonymous inner classes.

Include Getter/Setter

Controls whether auto-generation should be enabled for methods that follow the JavaBeans naming convention (Getter/Setter). Please note that you can control what methods should be recognized as Boolean Getters via a regular expression. Refer to “Boolean Getter Regex” for more information.

Since 1.3

Exclude Overridden/Implemented

Controls whether Javadoc comments should be generated for methods that are implementing/overriding others.

Example 2.820. Class hierarchy

public interface Foo {
    /**
     * Does foo.
     */
    public void doFoo();
}

public abstract class BaseFoo implements Foo {
    @Override public void doFoo() {
        ...
    }
}

public abstract class FooImpl extends BaseFoo {
    @Override public void doFoo() {
        ...
    }
}

With this option enabled, Jalopy would not generate Javadoc for doFoo() in BaseFoo or FooImpl, because they implement or override another method.

Since 1.8

Generate @see tags

Controls whether Javadoc generation for methods that are implementing or overriding others, creates @see tags to point to the referenced method. When disabled, Javadoc generation uses the descriptions given in the different templates.

Example 2.821. Generated Javadocs

package com.foo;


public interface Foo {
    /**
     * Does foo.
     */
    public void doFoo();
}

public abstract class BaseFoo implements Foo {
    
    /**
     * DOCME!
     */
    public void doFoo() { }

    /**
     * DOCME!
     */
    public void doBar() { }
}

public abstract class FooImpl extends BaseFoo {

    /**
     * DOCME!
     */
    @Override public void doFoo() { }
}

But when this option has been enabled, Jalopy automatically creates @see tags that references the overridden or implemented method in order to point to the documentation available there.

Example 2.822. Generated Javadocs

package com.foo;


public interface Foo {
    /**
     * Does foo.
     */
    public void doFoo();
}

public abstract class BaseFoo implements Foo {
    
    /**
     * @see com.foo.Foo#doFoo()
     */
    @Override public void doFoo() { }

    /**
     * DOCME!
     */
    public void doBar() { }
}

public abstract class FooImpl extends BaseFoo {

    /**
     * @see com.foo.BaseFoo$doFoo()
     */
    @Override public void doFoo() { }
}

Since 1.8

Reuse existing comments

When enabled, the textual contents of all existing comments that appear before a certain node are used as the description section (instead of the one defined in the template). Otherwise the generated Javadoc comment is simply inserted below any already existing comments.

Since 1.5

Example 2.823. Method without Javadoc comment

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

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

Example 2.824. Generated comment

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

But when the option is enabled, the result would be

Example 2.825. Generated comment that uses existing comment

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

Format bean property

Lets you control whether the value of the “property.name” local environment variable should be split into several chunks or just have its prefix stripped upon interpolation.

When enabled, the property name is determined from the method name by stripping the bean prefix and taking any upper case letter followed by a lower case letter and put a space in front of it. E.g. “getImportanceValue” would result in "Importance Value", “getABSValue” in "ABS Value" and “isValid” in “Valid”. The case of all chunks is adjusted according to the rules as sketched below.

8.8 Capitalization of inferred names.

When we use design patterns to infer a property or event name, we need to decide what rules to follow for capitalizing the inferred name. If we extract the name from the middle of a normal mixedCase style Java name then the name will, by default, begin with a capital letter. Java programmers are accustomed to having normal identifiers start with lower case letters. Vigorous reviewer input has convinced us that we should follow this same conventional rule for property and event names.

Thus when we extract a property or event name from the middle of an existing Java name, we normally convert the first character to lower case. However to support the occasional use of all upper-case names, we check if the first two characters of the name are both upper case and if so leave it alone. So for example,

“FooBah” becomes “fooBah”
“Z” becomes “z”
“URL” becomes “URL”

[taken from the JavaBeans Spec]

When disabled, just the bean prefix is stripped and the case of the first letter adjusted according to the rules laid out in the JavaBean spec.

Since 1.3

Example 2.826. Javadoc template for Setter

/**
 * Sets the value of the $property.name$ property.
 *
 * @param name $property.name$ property value.
 */
public void setImportanceValue(String value) {
    ...
}

Example 2.827. Generated Javadoc comment with formatted JavaBeans property name

/**
 * Sets the value of the Importance Value property.
 *
 * @param  name  importance value property value.
 */
public void setImportanceValue(String value) {
    ...
}

Example 2.828. Generated Javadoc comment with unformatted JavaBeans property name

/**
 * Sets the value of the ImportanceValue property.
 *
 * @param  name  importanceValue property value.
 */
public void setImportanceValue(String value) {
    ...
}

Enable for

The table component lets you selectively enable the auto-generation of missing Javadoc comments for specific code elements and access levels. Please note that you can selectively disable Javadoc generation in source code files by using a special pragma comment. Refer to the Pragma comments section for more information.

Disable for

Lets you disable Javadoc generation for declarations that either carry specific annotations, or within classes that extend a certain class or implement a certain interface.This way you could for example disable Javadoc generation for tests.

Use the Add... button to specify both annotation names and/or the type names of extends or implements clauses that should disable Javadoc generation when found.

Annotations must be specified in the marker annotation form, e.g. @Test or @Factory. You never include any parenthesized values. Special support is provided for the @Test annotation. If it can be found on the class level, all public members will be excluded from Javadoc generation as well.

Since 1.9.4

Example 2.829. Test file

public class FooTest {
    @Test public void test { }
}

could become

Example 2.830. @Test annotation disables Javadoc generation

/**
 * DOCME!
 *
 * @author   Joe Tiger
 * @version  $version$
 */
public class FooTest {
    @Test public void test { }
}

But you might also use

Example 2.831. Another test file

@Test
public class FooTest {
    public void test { }
}

which would effectively disable Javadoc generation for the whole class as it only contains public members.

For type names, please note that Javadoc generation will only be disabled for the members defined within a class—the class declaration itself is not affected. Please note further that comparison is done using exact string matching: you need to specify the type names exactly as they appear in the source files. ActionListener and java.awt.event.ActionListener are treated as two different type names. If you mix qualified and simple type names in your sources, you need to define both type names here.

Since 1.6

Example 2.832. Java source file with missing Javadoc

/** A sample class. */
public class Foo {
    class MyAction implements ActionListener {
        public void actionPerformed(ActionEvent ev) { }
    }
}

Javadoc generation without exclusions could look like:

Example 2.833. Javadoc generation without exclusion

/** A sample class. */
public class Foo {

    /**
     * DOCME!
     *
     * @author   Joe Tiger
     * @version  $version$
     */
    class MyAction implements ActionListener {

        /**
         * DOCME!
         *
         * @param  ev  DOCME!
         */
        public void actionPerformed(ActionEvent ev) { }
    }
}

But with Javadoc generation disabled for ActionListener, the result could look like:

Example 2.834. Javadoc generation with excluded interface

/** A sample class. */
public class Foo {

    /**
     * DOCME!
     *
     * @author   Joe Tiger
     * @version  $version$
     */
    class MyAction implements ActionListener {
        public void actionPerformed(ActionEvent ev) { }
    }
}

Please note how Javadoc is added for the inner class declaration, but not the inner class method!

2.8.14.4. Correction

Lets you control the Javadoc comment checking and auto-correction features.

Figure 2.72. Javadoc Correction settings page

Javadoc Correction settings page

Correct HTML

This feature lets you enforce valid HTML. When enabled, Jalopy ensures that the comments only contain valid HTML 4.01 markup. Missing tags like optional end tags will be inserted to ensure well-formed contents.

Example 2.835. Javadoc comment with missing paragraph tags

/**
 * Indicates the kinds of program element to which an annotation type
 * is applicable.  If a Target meta-annotation is not present on an
 * annotation type declaration, the declared type may be used on any
 * program element.  If such a meta-annotation is present, the compiler
 * will enforce the specified usage restriction.
 *
 * For example, this meta-annotation indicates that the declared type is
 * itself a meta-annotation type.  It can only be used on annotation type
 * declarations.
 */

Example 2.836. Javadoc comment with inserted paragraph tags

/**
 * Indicates the kinds of program element to which an annotation type
 * is applicable.  If a Target meta-annotation is not present on an
 * annotation type declaration, the declared type may be used on any
 * program element.  If such a meta-annotation is present, the compiler
 * will enforce the specified usage restriction.
 *
 * <p>For example, this meta-annotation indicates that the declared type
 * is itself a meta-annotation type.  It can only be used on annotation
 * type declarations.</p>
 */

Example 2.837. Javadoc comment with missing </li> tags

/**
 * Returns a short description of this throwable.
 * If this <code>Throwable</code> object was created with a non-null detail
 * message string, then the result is the concatenation of three strings: 
 * <ul>
 * <li> The name of the actual class of this object 
 * <li>": " (a colon and a space)
 * <li>The result of the {@link #getMessage} method for this object 
 * </ul>
 */

Example 2.838. Javadoc comment with inserted </li> tags

/**
 * Returns a short description of this throwable. If this <code>
 * Throwable</code> object was created with a non-null detail message
 * string, then the result is the concatenation of three strings:
 *
 * <ul>
 *   <li>The name of the actual class of this object</li>
 *   <li>": " (a colon and a space)</li>
 *   <li>The result of the {@link #getMessage} method for this object</li>
 * </ul>
 */

Since 1.0

Correct sentence punctuation

When enabled, ensures that the first sentence of the description section ends with punctuation. If no punctuation is present, a dot character will be added at the end of the first sentence. The first sentence is determined by either a blank line between two text chunks or by a HTML block tag. If no obvious sentence break could be found, the dot is added at the end of the description section.

Since 1.6

Example 2.839. Javadoc comment with missing period after first sentence

/**
 * The method used for creating the tree
 * <p>
 * This method adds an anonymous TreeSelectionListener to 
 * the returned JTree.  Upon receiving TreeSelectionEvents, 
 * this listener calls refresh with the selected node as a 
 * parameter. 
 */

Example 2.840. Reformatted Javadoc comment with added period after first sentence

/**
 * The method used for creating the tree.
 *
 * <p>This method adds an anonymous TreeSelectionListener to the
 * returned JTree. Upon receiving TreeSelectionEvents, this listener
 * calls refresh with the selected node as a parameter.
 */

Description Section

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 Section 2.8.14.5, “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

Example 2.841. Javadoc comment without descriptioin

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

will only be formatted to

Example 2.842. Inserted description

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

when Javadoc comment auto-generation is enabled for method declarations that have an access level of protected.

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

Example 2.843. Javadoc comment

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

will be formatted as

Example 2.844. Javadoc comment

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

because the Javadoc comment neither contains a @param nor a @return block tag. But

Example 2.845. Javadoc comment with @return tag

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

will be formatted as

Example 2.846. Javadoc comment with auto-generated description

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

because a @return tag can be found.

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

Example 2.847. Javadoc comment

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

would be formatted as

Example 2.848. Javadoc comment with auto-generated description

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

because the Javadoc comment contains no @see tag. But

Example 2.849. Javadoc comment with @see tag

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

would be formatted as

Example 2.850. Formatted Javadoc comment

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

because a @see tag can be found.

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

Example 2.851. Javadoc with missing description section

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

Example 2.852. Missing description generated from template

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

Example 2.853. Missing description generated from @return tag

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

Tag Section

Provides options to control the behavior for the block tags of 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. 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 Section 2.8.14.5, “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

Example 2.854. Javadoc comment

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

will only be formatted to

Example 2.855. Javadoc comment with auto-generated @return tag

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

when Javadoc comment auto-generation is enabled for method declarations that have an access level of protected.

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

Example 2.856. Javadoc comment without @return or @param

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

will be formatted as

Example 2.857. Javadoc comment without corrections

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

because the Javadoc comment neither contains a @param nor a @return block tag. But

Example 2.858. Javadoc comment with @param

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

will be formatted as

Example 2.859. Corrected Javadoc comment

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

because a @param tag can be found.

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 whether 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 Section 2.8.14.6.1.1, “Block tags”, Section 2.8.14.6.1.2, “In-line tags” and Appendix C, 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.

Example 2.860. Undocumented exception

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

    ...
}

Example 2.861. Added exception

/**
 * Description
 *
 * @param   rFile  input file.
 *
 * @throws  IOException            if an I/O problem occurred.
 * @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 resolution 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

Example 2.862. Generated missing throws clause

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

Example 2.863. No throws clause generated for runtime exception

/**
 * 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 declarations 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 Section 2.8.14.5, “Templates”.

Since 1.5

Example 2.864. Javadoc template

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

With the above shown template, upon reformatting Jalopy ensures that all existing class level Javadoc comments contain the @author tag. Thus, the following comment

Example 2.865. Javadoc comment

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

could become

Example 2.866. Javadoc comment after formatting

/**
 * 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 Section 2.4, “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.

Example 2.867. Generic method

/**
 * 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

Example 2.868. Generic method

/**
 * 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

Example 2.869. Javadoc with missing @return tag description

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

Example 2.870. Javadoc with @return tag description inserted from template

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

Example 2.871. Javadoc with @return tag description taken from description section

/**
 * 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

Example 2.872. Tags with missing description

/*
 * 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

Example 2.873. Tags with missing description

/**
 * 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

Example 2.874. Tagged missing descriptions

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

2.8.14.5. Templates

Lets you define templates to be inserted for the different declaration elements when Javadoc Generation (see Section 2.8.14.3, “Generation”) has been enabled. Each element (Class, Interface, Field, Constructor and Method) has its own template. Depending on the element type, a template consists of up to five parts that together form a valid Javadoc comment. When Javadoc formatting (see Section 2.8.14.1, “Format”) is enabled, the templates will be reformatted before they are inserted.

You can use variable expressions throughout your templates to insert various data automagically. See Section 2.4.3, “Local variables” for more information about the available variables.

Important

The templates also describe the formatting style for each element and are used to determine the description texts that are to be inserted for the Javadoc auto-correction feature (described in Section 2.8.14.4, “Correction”)

2.8.14.5.1. Class template

Lets you define the template for class and enum declarations (including inner classes).

Figure 2.73. Javadoc class template

Javadoc class template

Enter a valid Javadoc comment. The Preview window will update in real-time to reflect your changes.

Example 2.875. Class declaration with generated Javadoc

/**
 * DOCME!
 *
 * @author $author$
 * @version $Revision: #22 $, $Date: 2007/08/15 $
 */
public class CompilationUnit {
}

2.8.14.5.2. Interface template

Lets you define the template for interface and annotation declarations.

Figure 2.74. Javadoc interface template

Javadoc interface template

Enter a valid Javadoc comment. The Preview window will update in real-time to reflect your changes.

Example 2.876. Interface declaration with generated Javadoc

/**
 * DOCME!
 *
 * @author $author$
 * @version $Revision: #22 $, $Date: 2007/08/15 $
 */
public interface Saveable {
}

2.8.14.5.3. Enum template

Lets you define the template for enum declarations (includes inner enums).

Since 1.5

Figure 2.75. Javadoc enum template

Javadoc enum template

Enter a valid Javadoc comment. The Preview window will update in real-time to reflect your changes.

Example 2.877. Enum declaration with generated Javadoc

/**
 * DOCME!
 *
 * @author $author$
 * @version $Revision: #22 $, $Date: 2007/08/15 $
 */
public enum Week {
  ...
}

2.8.14.5.4. Field template

Lets you define the template for field declarations.

Figure 2.76. Javadoc field template

Javadoc field template

Enter a valid Javadoc comment. The Preview window will update in real-time to reflect your changes.

Example 2.878. Field declaration with generated Javadoc

/** DOCME! */
public String name;

2.8.14.5.5. Constructor template

Lets you define the template for constructor declarations.

Figure 2.77. Javadoc constructor template

Javadoc constructor template

Example 2.879. Constructor declaration with generated Javadoc

/**
 * DOCME!
 *
 * @param source DOCME!
 */
public CompilationUnit(String source) {
}

2.8.14.5.6. Method template

Lets you define the template for method declarations.

Figure 2.78. Javadoc method template

Javadoc method template

The Preview window will update in real-time to reflect your changes.

Example 2.880. Method declaration with generated Javadoc

/**
 * DOCME!
 *
 * @param source DOCME!
 *
 * @throws SyntaxException DOCME!
 */
public void compile(File source) throws SyntaxException {
}

2.8.14.5.7. Setter template

Lets you define the template for Setter methods (following the JavaBeans naming convention).

Figure 2.79. Javadoc Setter method template

Javadoc Setter method template

The JavaBeans specification defines a standard way in which the properties for a JavaBean instance should be accessed. This same technique can also be applied to regular classes and interfaces to access their attributes. The Setter template is used for all methods that look like setXxx() (also called mutator methods).

Since 1.1

Example 2.881. Setter method declaration with generated Javadoc

/**
 * Sets the value of the Importance Value property.
 *
 * @param name Importance Value property value.
 */
public void setImportanceValue(String value) {
}

You can use the Synchronize button to synchronize the template with the method declaration template.

2.8.14.5.8. Getter template

Lets you define the template for Getter methods (following the JavaBeans naming convention).

Figure 2.80. Javadoc Getter method template

Javadoc Getter method template

The JavaBeans specification defines a standard way in which the properties for a JavaBean instance should be accessed. This same technique can also be applied to regular classes and interfaces to access their attributes.

The Getter template is used for all methods that look like getXxx() (also called accessor methods) and all methods matching the specified Boolean Getter pattern (refer to “Boolean Getter Regex” for further information).

Since 1.1

Example 2.882. Getter method declaration with generated Javadoc

/**
 * Returns the value of the Importance Value property.
 *
 * @return the Importance Value property.
 */
public void getImportanceValue() {
}

You can use the Synchronize button to synchronize the template with the method declaration template. Please note that you need to apply any changes made to the method declaration template first in order to see the changes propagated here.

2.8.14.6. Tags

Lets you define custom tags that should be recognized by the Javadoc parser.

2.8.14.6.1. Javadoc

Lets you define custom Javadoc tags. You need to specify all non-standard tags that you use, i.e. all tags not defined in HTML 4.01, in order to see the Javadoc parser behave correctly. Otherwise errors are generated for every tag that is unknown to the system.

Figure 2.81. Define Custom Javadoc Tags

Define Custom Javadoc Tags

Refer to the tables below to learn about the tags that are supported by default.

2.8.14.6.1.1. Block tags

Lets you define custom Javadoc block tags. The table below shows the Javadoc block tags that are supported by default.

Table 2.7. Build-in Javadoc block tags

NameSince
@author1.0
@beaninfo1.0
@deprecated1.0
@exception1.0
@jalopy.group1.1
@jalopy.group-order1.1
@jalopy.group_order1.1
@param1.0
@return1.0
@see1.0
@serial1.0
@serialData1.0
@serialField1.0
@since1.0
@throws1.0
@todo1.0
@version1.0

Use the Add... and Remove buttons to add or remove items to and from the list.

Figure 2.82. Add new Block Tag

Add new Block Tag

Valid block tags have the form @[a-zA-Z]+, e.g. @pre.

2.8.14.6.1.2. In-line tags

Lets you define custom Javadoc in-line tags. The table below shows the Javadoc in-line tags that are supported by default.

Table 2.8. Build-in Javadoc in-line tags

NameSince
@code1.3
@docRoot1.0
@inheritDoc1.0
@link1.0
@linkPlain1.0
@literal1.3
@value1.0

Use the Add... and Remove buttons to add or remove items to and from the list.

Figure 2.83. Add new In-line Tag

Add new In-line Tag

Valid in-line tags have the form @[a-zA-Z]+, e.g. @root.

2.8.14.6.2. XDoclet

Lets you define custom XDoclet tags.

Figure 2.84. Define Custom XDoclet Tags

Define Custom XDoclet Tags

Refer to Appendix C, Build-in XDoclet tags for the tags that are supported by default. Use the Add... and Remove buttons to add or remove items to and from the list.

Figure 2.85. Add new XDoclet Tag

Add new XDoclet Tag

Valid XDoclet tags have the form @[a-zA-Z.:_-]+, e.g. @jonas.session-timeout.

Since 1.0

2.8.14.6.3. HTML

Lets you define custom HTML tags.

Figure 2.86. Define Custom HTML Tags

Define Custom HTML Tags

The standard supported tags are those of the HTML 4.01 standard. Use the Add... and Remove buttons to add or remove items to and from the list.

Figure 2.87. Add new HTML Tag

Add new HTML Tag

Since 1.0