[Skip to content]
TRIEMAX Software
You are here: Home > Products > Jalopy >

### 2.6.9. Javadoc

Lets you control all Javadoc-related options.

Javadoc is a tool that generates API documentation out of comments which follow a special syntax and are extracted directly from Java source files. Jalopy includes functionality to generate and maintain such comments automatically.

#### 2.6.9.1. Format

Lets you control the Javadoc formatting options.

Figure 2.68. Javadoc settings page

##### 2.6.9.1.1. Format comments

Enables or disables the formatting of Javadoc comments.

When enabled Javadoc comments are re-formatted according to the options specified below.

Please note that the formatting style of leading and closing comment delimiter and leading asterixes are determined by analyzing the templates defined for each declaration element. Refer to Section 2.6.9.5, "Templates" for more information about the Javadoc templates.

##### 2.6.9.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 like the tag.

Since 1.6

Example 2.753. 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.754. 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.755. 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.756. 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 description/name

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.

Please note that you need to have the indentation of descriptions enabled to see descriptions aligned (see above).

Since 1.0

Example 2.757. 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.758. 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 intended 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.759. 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.760. Javadoc with aligned tag attributes

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

###### Sort

When enabled, block tags are sorted according to the order recommended by the Javadoc creators (See http://java.sun.com/j2se/javadoc/writingdoccomments/ for more information). Otherwise the 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.761. Unsorted block 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.762. Sorted block 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
     *     attribute: visualUpdate true
     *         bound: true
     *   description: The object that contains the data to be drawn
     */

###### 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.69. 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.6.9.1.3. Compact comments

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

###### Classes

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.763. 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.764. Class Javadoc comment (shortened)

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

###### Enums

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

Since 1.7

Example 2.765. Enum Javadoc comment

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

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

Example 2.766. Enum Javadoc comment (shortened)

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

###### Fields

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

Example 2.767. 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.768. Field Javadoc comment (shortened)

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

###### Method comments in single line

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.769. 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.770. Method Javadoc comment (shortened)

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

###### Single Block tag

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.771. Single block tag

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

Example 2.772. Single block tag compacted

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

###### Remove stars in <pre> tags

Lets you remove leading stars in preformatted 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 preformatted sections or have them printed.

Since 1.6

Example 2.773. 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.774. 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.775. 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.776. 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
     */

#### 2.6.9.2. Line Wrapping

##### 2.6.9.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.777. 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.778. 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.6.9.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.779. 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.780. 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.6.9.3. Generation

Controls the general handling of Javadoc comments.

Figure 2.70. Javadoc settings page

##### 2.6.9.3.1. General

Lets you control the general Javadoc comment auto-generation options.

Please refer to Section 2.6.9.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

##### 2.6.9.3.2. Options

###### Include inner classes

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

###### Include Getter/Setter

Controls whether the 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 the sorting section 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.781. Class hierarchy

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

    public abstract class BaseFoo implements Foo {
        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.

This functionality will allow you to turn on Javadoc generation, but avoid having to create @see tags (which might be considered bad).

Since 1.8

###### Generate @see tags

Controls whether Javadoc generation for methods that are implementing or overriding others, creates @see tags to reference the overridden method.

Normally, Javadoc generation uses the descriptions given in the different templates.

Example 2.782. 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.783. Generated Javadocs

    package com.foo;

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

    public abstract class BaseFoo implements Foo {

        /**
         * @see com.foo.Foo#doFoo()
         */
        public void doFoo() {
            ...
        }

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

    public abstract class FooImpl extends BaseFoo {

        /**
         * @see com.foo.Foo$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.784. 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.785. 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.786. 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"

> (see http://java.sun.com/products/javabeans/docs/beans.101.pdf)

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.787. 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.788. Generated Javadoc comment with formatted bean property name

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

Example 2.789. Generated Javadoc comment with unformatted bean 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 within classes that extend a certain class or implement a certain interface.

This option is useful if you generally want to document inner classes, but obmit documentation for certain inner classes like e.g. Swing listeners.

Please note that Javadoc generation will only be disabled for the methods, fields etc. 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 name exactly as it appears in the source file. `ActionListener` and `java.awt.event.ActionListener` are treated as two different type names. If you mix qualified and simple type names in your source, you need to define both type names here.

Use the Add... button to define the type names of `extends` or `implements` clauses that should disable Javadoc generation when found.

Since 1.6

Example 2.790. 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.791. 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.792. Javadoc generation with exclusion

    /**
     * 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 omitted for the contained method!

#### 2.6.9.4. Correction

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

Figure 2.71. Javadoc Correction settings page

Please note that unlike with the Open Source version, auto-correction may be enabled independently from Javadoc formatting. Still, it is recommended to enable the formatting of comments too, because otherwise you may encounter slight style differences when descriptons or tags are inserted/removed.

##### 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.793. 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.794. 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.795. 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.796. 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.797. 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.798. 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.6.9.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.799. Insert description when auto-generation enabled

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

will only be formatted to

    /**
     * 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.800. Insert description only when @param or @return tag present

With this option enabled, code like

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

will be formatted as

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

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

But

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

will be formatted as

    /**
     * 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.801. Insert description only when no @see tag present

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

would be formatted as

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

because the Javadoc comment contains no `@see` tag.

But

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

would be formatted as

    /**
     * @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.802. Javadoc with missing description section

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

Example 2.803. Missing description generated from template

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

Example 2.804. 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 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 Section 2.6.9.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.805. Only correct tags when auto-generation enabled

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

will only be formatted to

    /**
     * @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.806. Only correct tags when @param or @return tag present

With this option enabled, code like

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

will be formatted as

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

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

But

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

will be formatted as

    /**
     * @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 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 Section 2.6.9.6.1.1, "Block tags", Section 2.6.9.6.1.2, "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.

Example 2.807. Undocumented exception

    /**
     * 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();

        ...
    }

Example 2.808. Added exception

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

Example 2.809. Generated missing throws clause

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

Example 2.810. 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 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 Section 2.6.9.5, "Templates".

Since 1.5

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

Example 2.811. Javadoc template

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

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

Example 2.812. Javadoc comment

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

could become

Example 2.813. 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.3, "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.814. 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.815. 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.816. Javadoc with missing @return tag description

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

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

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

Example 2.818. 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.819. 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.820. Tags with missing desccription

    /**
     * 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.821. Tagged missing descriptions

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

#### 2.6.9.5. Templates

Lets you define templates to be inserted for the different declaration elements. 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.6.9.1, "Format") is enabled, the templates will be reformatted before they are inserted.

Please note that the templates also describe the style of Javadoc formatting for each element and are used to determine the description texts that are to be inserted for the Javadoc auto-correction feature (see Section 2.6.9.4, "Correction").

You can use variable expressions throughout your templates. See Section 2.3.3, "Local variables" for more information about the available variables.

##### 2.6.9.5.1. Class template

Figure 2.72. Javadoc class template

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

Example 2.822. Class declaration with generated Javadoc

    /**
     * DOCME!
     *
     * @author $author$
     * @version $Revision: #21 $, $Date: 2006/10/17 $
     */
    public class CompilationUnit {
    }

##### 2.6.9.5.2. Interface template

Figure 2.73. Javadoc interface template

Lets you define the template for interface and annotation declarations.

Example 2.823. Interface declaration with generated Javadoc

    /**
     * DOCME!
     *
     * @author $author$
     * @version $Revision: #21 $, $Date: 2006/10/17 $
     */
    public interface Saveable {
    }

##### 2.6.9.5.3. Enum template

Figure 2.74. Javadoc enum template

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

Since 1.5

Example 2.824. Enum declaration with generated Javadoc

    /**
     * DOCME!
     *
     * @author $author$
     * @version $Revision: #21 $, $Date: 2006/10/17 $
     */
    public enum Week {
      ...
    }

##### 2.6.9.5.4. Field template

Figure 2.75. Javadoc field template

Lets you define the template for field declarations.

Example 2.825. Field declaration with generated Javadoc

    /** DOCME! */
    public String name;

##### 2.6.9.5.5. Constructor template

Figure 2.76. Javadoc constructor template

Lets you define the template for constructor declarations.

Example 2.826. Constructor declaration with generated Javadoc

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

##### 2.6.9.5.6. Method template

Figure 2.77. Javadoc method template

Lets you define the template for method declarations.

Example 2.827. Method declaration with generated Javadoc

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

##### 2.6.9.5.7. Setter template

Figure 2.78. Javadoc Setter method template

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

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.828. 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.6.9.5.8. Getter template

Figure 2.79. Javadoc Getter method template

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

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 acessor methods) and all methods matching the specified Boolean Getter pattern (refer to the Sorting section).

Since 1.1

Example 2.829. 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.6.9.6. Tags

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

##### 2.6.9.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.80. Define Custom Javadoc Tags

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

###### 2.6.9.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.4. Build-in Javadoc block tags

Name | Since
--- | ---
@author | 1.0
@beaninfo | 1.0
@deprecated | 1.0
@exception | 1.0
@jalopy.group | 1.1
@jalopy.group-order | 1.1
@jalopy.group_order | 1.1
@param | 1.0
@return | 1.0
@see | 1.0
@serial | 1.0
@serialData | 1.0
@serialField | 1.0
@since | 1.0
@throws | 1.0
@todo | 1.0
@version | 1.0

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

Figure 2.81. Add new Block Tag

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

###### 2.6.9.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.5. Build-in Javadoc in-line tags

Name | Since
--- | ---
@code | 1.3
@docRoot | 1.0
@inheritDoc | 1.0
@link | 1.0
@linkPlain | 1.0
@literal | 1.3
@value | 1.0

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

Figure 2.82. Add new In-line Tag

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

##### 2.6.9.6.2. XDoclet

Lets you define custom XDoclet tags.

Figure 2.83. Define Custom XDoclet Tags

Refer to Appendix B, 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.84. Add new XDoclet Tag

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

Since 1.0

##### 2.6.9.6.3. HTML

Lets you define custom HTML tags.

Figure 2.85. 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.86. Add new HTML Tag

Since 1.0