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 Section 2.6.9.5, "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 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 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
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
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
Controls the general handling of Javadoc comments.
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
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,
(see http://java.sun.com/products/javabeans/docs/beans.101.pdf)"FooBah" becomes "fooBah"
"Z" becomes "z"
"URL" becomes "URL"
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!
Lets you control the Javadoc comment checking and auto-correction features.
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.
*/
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() { ... }
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:
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
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.
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.
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.
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.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.
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.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.
Valid in-line tags have the form @[a-zA-Z]+, e.g. @root.
Lets you 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.
Valid XDoclet tags have the form @[a-zA-Z.:_-]+, e.g. @jonas.session-timeout.
Since 1.0
Lets you 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.
Since 1.0