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.
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
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.
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
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.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
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.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
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"
*/
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. |
*/ |
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
Controls the auto-generation of missing Javadoc comments.
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
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
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!
Lets you control the Javadoc comment checking and auto-correction features.
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.
*/
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
will be formatted as
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
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() { ... }
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
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
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) {}
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.
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”)
Lets you define the template for class and enum declarations (including inner classes).
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 { }
Lets you define the template for interface and annotation declarations.
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 { }
Lets you define the template for enum declarations (includes inner enums).
Since 1.5
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 { ... }
Lets you define the template for field declarations.
Enter a valid Javadoc comment. The Preview window will update in real-time to reflect your changes.
Lets you define the template for constructor declarations.
Example 2.879. Constructor declaration with generated Javadoc
/** * DOCME! * * @param source DOCME! */ public CompilationUnit(String source) { }
Lets you define the template for method declarations.
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 { }
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.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.
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 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.
Lets you define custom tags that should be recognized by the Javadoc parser.
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.
Refer to the tables below to learn about the tags that are supported by default.
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
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.
Valid block tags have the form @[a-zA-Z]+
, e.g.
@pre
.
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
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.
Valid in-line tags have the form @[a-zA-Z]+
, e.g.
@root
.
Lets you 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.
Valid XDoclet tags have the form @[a-zA-Z.:_-]+
, e.g.
@jonas.session-timeout
.
Since 1.0