As explained in Chapter 1, Java supports three types of comments. The first two are the // and the /* */. The third type is called a documentation comment. It begins with the character sequence /**. It ends with */. Documentation comments allow you to embed information about your program into the program itself. You can then use the javadoc utility program (supplied with the JDK) to extract the information and put it into an HTML file. Documentation comments make it convenient to document your programs. You have almost certainly seen documentation that uses such comments, because that is the way the Java API library was documented. Beginning with JDK 9, javadoc includes support for modules.

The javadoc Tags

The javadoc utility recognizes several tags, including those shown here:

Document tags that begin with an “at” sign (@) are called block tags (also called stand-alone tags), and they must be used at the beginning of their own line. Tags that begin with a brace, such as {@code}, are called inline tags, and they can be used within a larger description. You may also use other, standard HTML tags in a documentation comment. However, some tags such as headings should not be used, because they disrupt the look of the HTML file produced by javadoc.

As it relates to documenting source code, you can use documentation comments to document classes, interfaces, fields, constructors, methods, packages, and modules. In all cases, the documentation comment must immediately precede the item being documented. Some tags, such as @see, @since, and @deprecated, can be used to document any element. Other tags apply to only the relevant elements. Several key tags are examined next.

NOTE

As one would expect, the capabilities of javadoc and the documentation comment tags have evolved over time, often in response to new Java features. You will want to refer to the javadoc documentation for information on the latest javadoc features.

@author

The @author tag documents the author of a program element. It has the following syntax:

@author description

Here, description will usually be the name of the author. You will need to specify the -author option when executing javadoc in order for the @author field to be included in the HTML documentation.

{@code}

The {@code} tag enables you to embed text, such as a snippet of code, into a comment. That text is then displayed as-is in code font, without any further processing such as HTML rendering. It has the following syntax:

{@code code-snippet}

@deprecated

The @deprecated tag specifies that a program element is deprecated. It is recommended that you include @see or {@link} tags to inform the programmer about available alternatives. The syntax is the following:

@deprecated description

Here, description is the message that describes the deprecation. The @deprecated tag can be used in documentation for fields, methods, constructors, classes, modules, and interfaces.

{@docRoot}

{@docRoot} specifies the path to the root directory of the current documentation.

@exception

The @exception tag describes an exception to a method. Today, @throws is the preferred alternative, but @exception is still supported. It has the following syntax:

@exception exception-name explanation

Here, the fully qualified name of the exception is specified by exception-name, and explanation is a string that describes how the exception can occur. The @exception tag can be used only in documentation for a method or constructor.

@hidden

The @hidden tag prevents an element from appearing in the documentation.

{@index}

The {@index} tag specifies an item that will be indexed, and thus found when using the search feature. It has the following syntax:

{@index term usage-str }

Here, term is the item (which can be a quoted string) to be indexed. usage-str is optional. Thus, in the following @throws tag, {@index} causes the term "error" to be added to the index:

@throws IOException On input {@index error}.

Note that the word “error” is still displayed as part of the description. It’s just that now it is also indexed. If you include the optional usage-str, then that description will be shown in the index and in the search box to indicate how the term is used. For example, {@index error Serious execution failure} will show “Serious execution failure” under "error" in the index and in the search box.

{@inheritDoc}

This tag inherits a comment from the immediate superclass.

{@link}

The {@link} tag provides an in-line link to additional information. It has the following syntax:

{@link mod-name/pkg-name.class-name#member-name text}

Here, mod-name/pkg-name.class-name#member-name specifies the name of a class or method to which a link is added, and text is the string that is displayed. The text field is optional. If not included, member-name is displayed as the link. Notice that the module name (if present) is separated from the package name with a /. For example,

{@link java.base/java.io.Writer#write}

defines a link to the write( ) method of Writer in java.io, in the module java.base.

{@linkplain}

The {@linkplain} tag inserts an in-line link to another topic. The link is displayed in plain-text font. Otherwise, it is similar to {@link}.

{@literal}

The {@literal} tag enables you to embed text into a comment. That text is then displayed as-is, without any further processing such as HTML rendering. It has the following syntax:

{@literal description}

Here, description is the text that is embedded.

@param

The @param tag documents a parameter. It has the following syntax:

@param parameter-name explanation

Here, parameter-name specifies the name of a parameter. The meaning of that parameter is described by explanation. The @param tag can be used only in documentation for a method, a constructor, or a generic class or interface.

@provides

The @provides tag documents a service provided by a module. It has the following syntax:

@provides type explanation

Here, type specifies a service provider type and explanation describes the service provider.

@return

The @return tag describes the return value of a method. It has two forms. The first is the block tag show here.

@return explanation

Here, explanation describes the type and meaning of the value returned by a method. Thus, the tag can be used only in documentation for a method. JDK 16 added an inline tag version:

{@return explanation}

This form must be at the top of the method’s documentation comment.

@see

The @see tag provides a reference to additional information. Two commonly used forms are shown here:

@see anchor

@see mod-name/pkg-name.class-name#member-name text

In the first form, anchor is a link to an absolute or relative URL. In the second form, mod-name/pkg-name.class-name#member-name specifies the name of the item, and text is the text displayed for that item. The text parameter is optional, and if not used, then the item specified by mod-name/pkg-name.class-name#member-name is displayed. The member name, too, is optional. Thus, you can specify a reference to a module, package, class, or interface in addition to a reference to a specific method or field. The name can be fully qualified or partially qualified. However, the dot that precedes the member name (if it exists) must be replaced by a hash character. There is a third form of @see that lets you simply specify a text-based description.

@since

The @since tag states that an element was introduced in a specific release. It has the following syntax:

@since release

Here, release is a string that designates the release or version in which this feature became available.

{@summary}

The {@summary} tag explicitly specifies a summary for an item. It must be the first tag in the documentation for the item. It has the following syntax:

@summary explanation

Here, explanation provides a summary of the tagged item, which can span multiple lines. Without the use of {@summary}, the first line in an item’s documentation comment is used as the summary.

@throws

The @throws tag has the same meaning as the @exception tag, but is now the preferred form.

@uses

The @uses tag documents a service provider needed by a module. It has the following syntax:

@uses type explanation

Here, type specifies a service provider type and explanation describes the service.

{@value}

{@value} has two forms. The first displays the value of the constant that it precedes, which must be a static field. It has this form:

{@value}

The second form displays the value of a specified static field. It has this form:

{@value pkg.class#field}

Here, pkg.class#field specifies the name of the static field.

@version

The @version tag specifies the version of a program element. It has the following syntax:

@version info

Here, info is a string that contains version information, typically a version number, such as 2.2. You will need to specify the -version option when executing javadoc in order for the @version field to be included in the HTML documentation.

The General Form of a Documentation Comment

After the beginning /**, the first line or lines become the main description of your class, interface, field, constructor, method, or module. After that, you can include one or more of the various @ tags. Each @ tag must start at the beginning of a new line or follow one or more asterisks (*) that are at the start of a line. Multiple tags of the same type should be grouped together. For example, if you have three @see tags, put them one after the other. In-line tags (those that begin with a brace) can be used within any description.

Here is an example of a documentation comment for a class:

What javadoc Outputs

The javadoc program takes as input your Java program’s source file and outputs several HTML files that contain the program’s documentation. Information about each class will be in its own HTML file. javadoc will also output an index and a hierarchy tree. Other HTML files can be generated. Beginning with JDK 9, a search box feature is also included.

An Example That Uses Documentation Comments

Following is a sample program that uses documentation comments. Notice the way each comment immediately precedes the item that it describes. After being processed by javadoc, the documentation about the SquareNum class will be found in SquareNum.html.