In the Auto Comment Tool, you can see if your source code has valid Javadoc
comments and create or edit the comments when necessary. You open the Auto Comment
Tool by right-clicking the file you want to document in the Filesystems window
or Source Editor and choosing Tools Auto
Comment from the contextual menu.
The entities in your source code that have Javadoc comments are listed on the left of the Auto Comment Tool. The filter toolbar enables you to control how data is shown in the Auto Comment tool. The following table describes the buttons on the toolbar.
Toolbar Button |
Description |
---|---|
![]() |
Switches the display of classes and members with full Javadoc comments |
![]() |
Switches the display of classes and members with partial or erroneous Javadoc comments |
![]() |
Switches the display of classes and members with no Javadoc comments |
![]() |
Switches the display of public methods |
![]() |
Switches the display of methods with default access |
![]() |
Switches the display of methods with protected access |
![]() |
Switches the display of private methods |
If an entity has a missing or incorrect Javadoc comment, you can click a command button to edit the command. The following table lists the command buttons.
Button Name | Description |
---|---|
Auto Correct | Automatically corrects any tagging errors or generates missing
tags on method
constructors. For example, if your code includes the method
public String myMethod(Object param1, Object param2){}and you click Auto Correct, the following tags are generated in the Tag pane of the Javadoc window and in the Source Editor: @param param1 @param param2 @return |
View Source | Opens the file in the Source Editor with the insertion point at the selected entity |
Refresh | Updates the Auto Comment Tool with changes made in the source file (for example, in the Source Editor) |
You can create or edit the text of a Javadoc comment in the Javadoc Comment Text panel of the Auto Comment Tool. The first sentence of the comment should be a summary description of the declared entity. The text may include HTML elements (such as <B> and <I>) for formatting the description. Heading elements (such as <H1> and <H2>) are reserved for use by the Javadoc tool. You can use the command buttons at the bottom of the dialog box to include the HTML elements <B>, <I>, <U>, <CODE>, and <PRE> and the Javadoc {@link} in the description. For example:
/** * Returns the Class of this <I>Object</I>. * Java has a runtime representation for * classes--a descriptor of type Class-- * which the method getClass() returns for * any Object. */You do not need to type the characters /** and */ or the leading asterisks in the Javadoc Comment dialog box. These characters are automatically included when the IDE adds the comment to the source code.
You can create or edit the tags of a Javadoc comment in the Tags panel of the Auto Comment Tool. A Javadoc tag starts with the character @ followed by a special keyword. Tags are case sensitive. A Javadoc tag enables you to automatically generate information for the API documentation. For example, @author name adds an author entry with the specified name to the generated documentation. A tag must appear at the beginning of a line (otherwise it is treated as normal text). By convention, tags with the same name are grouped together. The following comment includes four Javadoc tags:
/** * A class representing a screen window. * For example: * Window win = new Window(parent); * win.show(); * * @author Haley J. Ryan * @version 1.3 00/08/08 * @see java.awt.BaseWindow * @see java.awt.Button */
To add a Javadoc tag to your comment, click New, select a Javadoc tag or type a new tag, and click OK. The tag is added to the Tags pane of the Javadoc Comment dialog box. In the Description field, type the text of the tag. The text may include HTML elements (such as <B> and <I>) and the inline Javadoc tag {@link}.
See Also | |
---|---|
Entering Javadoc Comments in Source Code |