The Stat Data Provider Inc. development team scours their code and frantically attempts to piece together a development guide. Unfortunately, they have forgotten the details of how certain portions work. The Javadoc(TM) tool can deter such a situation from showing its ugly face. In this article, the reader is guided through self-documenting code in a structured manner to generate Java(TM) API documentation.
Using Javadoc - Java Documentation Comments (Page 2 of 5 )
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.