Where Tags Can Be Used
The following sections describe where the tags can be used. Note that these tags can be used in all doc comments: @see
, @since
, @deprecated
, {@link}
, {@linkplain}
, and {@docroot}
.
Overview Documentation Tags
Overview tags are tags that can appear in the documentation comment for the overview page (which resides in the source file typically named overview.html
). Like in any other documentation comments, these tags must appear after the main description.
NOTE - The {@link}
tag has a bug in overview documents in version 1.2 – the text appears properly but has no link. The {@docRoot}
tag does not currently work in overview documents.
Overview Tags |
---|
@see |
@since |
@author |
@version |
{@link} |
{@linkplain} |
{@docRoot} |
Package Documentation Tags
Package tags are tags that can appear in the documentation comment for a package (which resides in the source file named package.html
or package-info.java
). The @serial
tag can only be used here with the include
orexclude
argument.
Package Tags |
---|
@see |
@since |
@serial |
@author |
@version |
{@link} |
{@linkplain} |
{@docRoot} |
Class and Interface Documentation Tags
The following are tags that can appear in the documentation comment for a class or interface. The @serial
tag can only be used here with the include
or exclude
argument.
Class/Interface Tags |
---|
@see |
@since |
@deprecated |
@serial |
@author |
@version |
{@link} |
{@linkplain} |
{@docRoot} |
An example of a class comment:
/** * A class representing a window on the screen. * For example: * <pre> * Window win = new Window(parent); * win.show(); * </pre> * * @author Sami Shaio * @version 1.15, 13 Dec 2006 * @see java.awt.BaseWindow * @see java.awt.Button */ class Window extends BaseWindow { ... }
Field Documentation Tags
The following are the tags that can appear in the documentation comment for a field.
Field Tags |
---|
@see |
@since |
@deprecated |
@serial |
@serialField |
{@link} |
{@linkplain} |
{@docRoot} |
{@value} |
An example of a field comment:
/** * The X-coordinate of the component. * * @see #getLocation() */ int x = 1263732;
Constructor and Method Documentation Tags
The following are the tags that can appear in the documentation comment for a constructor or method, except for @return
, which cannot appear in a constructor, and {@inheritDoc}
, which has certain restrictions. The @serialData
tag can only be used in the doc comment for certain serialization methods.
Method/Constructor Tags |
---|
@see |
@since |
@deprecated |
@param |
@return |
@throws and @exception |
@serialData |
{@link} |
{@linkplain} |
{@inheritDoc} |
{@docRoot} |
An example of a method doc comment:
/** * Returns the character at the specified index. An index * ranges from <code>0</code> to <code>length() - 1</code>. * * @param index the index of the desired character. * @return the desired character. * @exception StringIndexOutOfRangeException * if the index is not in the range <code>0</code> * to <code>length()-1</code>. * @see java.lang.Character#charValue() */ public char charAt(int index) { ... }