Auto Comment Tool

See Also

The IDE's Auto Comment Tool enables you to determine if your source code's Javadoc comments are valid as well as edit or even create the comments when necessary. The source code entities that have Javadoc comments are listed in the left pane and the tags and comments themselves are displayed in the right pane.

You open the Auto Comment Tool by right-clicking the file you want to document in the Projects window or Source Editor and choosing Tools > Auto Comment from the contextual menu.

Filter Toolbar

The filter toolbar enables you to control which classes and members are displayed in the Auto Comment tool. The following table describes the buttons on the toolbar.

Toolbar
Button
Description
OK icon Switches the display to classes and members with full Javadoc comments
Error icon Switches the display to classes and members with partial or erroneous Javadoc comments
Missing icon Switches the display to classes and members with no Javadoc comments
Public icon Switches the display to public methods
Package icon Switches the display to methods with default access
Protected icon Switches the display to methods with protected access
Private icon Switches the display to private methods

Command Buttons

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.

If an entity has a missing or incorrect Javadoc comment, you can click a command button to edit the command. The following list describes the command buttons.

Javadoc Comment Text

You can create or edit the text of a Javadoc comment in the Auto Comment Tool's Javadoc Comment Text pane. 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 window 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 Text field. These characters are automatically included when the IDE adds the comment to the source code.

Tags

You can create or edit the tags of a Javadoc comment in the Tags pane 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. 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

Legal Notices