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.
Lets you control the Javadoc formatting options.
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 the section called "Templates" for more information about the Javadoc templates.
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.
Select an entry in the list and use the and 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
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
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
When enabled, Javadoc comments will be printed in a single line, when possible.
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
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