javadoc tags

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) {
       ...
    }