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.
Lets you control the Javadoc formatting options.
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 the section called “Templates” for more information about 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 with the tag.
Since 1.6
Example 2.776. 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.777. 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.778. 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.779. 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.780. 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.781. 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.782. 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.783. 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.784. 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.785. 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.786. 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.787. 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.
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 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
When enabled, Javadoc comments will be printed in a single line, when possible.
Example 2.789. 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
When enabled, Javadoc comments will be printed in a single line, when possible.
Field comments
Lets you specify how Javadoc comments of fields or enum constants, that fit into one line should be printed.
Example 2.792. 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.793. 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.794. 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.795. 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
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.798. Single XDoclet attribute
/** * @weblogic.transaction-descriptor * trans-timeout-seconds = "122" */ class Demo{ }
Example 2.799. 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.800. 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.801. 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.802. 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.803. 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.804. 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.805. 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"
*/