In the Auto Comment Tool, you can see whether an entity in
your source code has a valid Javadoc comment and create (or edit)
the comment when necessary.
Open the Auto Comment Tool from the Explorer by
right-clicking the source file that
you want to document and choosing Tools Auto Comment.
![]() |
Valid Javadoc comment |
![]() |
Partial or erroneous Javadoc comment |
![]() |
No Javadoc comment |
![]() |
Public |
![]() |
Package |
![]() |
Protected |
![]() |
Private |
Selecting an entity provides additional information on its Javadoc comment: the Details pane shows errors in the comment, the Javadoc Comment Text field shows the text of the comment, and the Tags field shows the tags in the comment. If an entity has a missing or incorrect Javadoc comment, you can click a command button to edit it as follows:
Auto Correct | Opens the Javadoc Comment dialog box and automatically corrects any tagging errors in the comment |
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) |
<B>
and <I>
) for formatting the description. Heading elements (such as <H1>
and <H2>
) are reserved for use by Javadoc.
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 the Javadoc Comment dialog box. These characters are automatically
included when the IDE adds the comment to the source
code.
@
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 Lynne Sim * @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}
.
To delete a tag from the list, select the tag and click Delete. To change the order of the tags, select a tag and move it with the Move Up and Move Down buttons.
See also | |
---|---|
Adding a Javadoc Comment to Source Code
Customizing the Output of Javadoc |