Using Javadoc

Java provides a documentation comment taking the format found in Listing 1. Javadoc comments are used to describe classes, variables, objects, and methods.  A Javadoc comment is placed above the element it is documenting. 

Listing 1: JavaDoc Comment

Line 1: /** Description of the element being documented
Line 2: * @tagA Description of tagA
Line 3: * @tagB Description of tagB
Line 4: */

There are a few elements to notice in the snippet above. The first is the beginning of the Java documentation comment begins with /** (Line 1) and ends with */ (Line 4).

Next, as the code snippet states, the first part of the comment should describe the documented element (Line 1). The upcoming exercise will illustrate the Javadoc tool’s interpretation of this description.

Finally, note the presence of tags in the code snippet (Lines 2 & 3). There are a number of predefined tags that can be used to describe a given element.  Some of these include:

@author text – the element’s author (only used for Java classes)

@version text – the element’s version number (only used for Java classes)

@param name description – describes the parameters of a method accompanied by a description (used for Java methods)

@return text – describes the value returned by a method (used for Java methods)

@exception exceptionClassName description – states the exceptions that a given method throws with an associated description.

@deprecated – used to state that the element being described has been deprecated.  When you use this tag, a deprecation warning will be issued when you compile a Java program using the element in question.

@since text – describes the product version when the element was added to the API specification

Note that there are a number of other tags that we have not discussed.  A good resource to learn more about all the tags in your Javadoc arsenal is the How to Write Doc Comments for the Javadoc Tool reference.