Java documentation comments
Java has only three annotation methods. The first two are // and /* */, and the third type is called a description comment, which ends with /**Start with*/.
Description comments allow you to embed information about the program into the program. You can use javadoc tool software to generate information and output it to an HTML file.
Description comments are for you to record information about your program in a more comprehensive way.
javadoc Tags
The javadoc tool software recognizes the following tags:
| Tag | Description | Example |
|---|---|---|
| @author | Identify the author of a class | @author description |
| @deprecated | Name an expired class or member | @deprecated description |
| {@docRoot} | Specify the path to the current document root directory | Directory Path |
| @exception | Mark an exception thrown by a class | @exception exception-name explanation |
| {@inheritDoc} | Annotations inherited from direct parent class | Inherits a comment from the immediate surperclass. |
| {@link} | Insert a link to another topic | {@link name text} |
| {@linkplain} | Insert a link to another topic, but display the link in plain text font | Inserts an in-line link to another topic. |
| @param | Describe the parameters of a method | @param parameter-name explanation |
| @return | Describe the return value type | @return explanation |
| @see | Specify a link to another topic | @see anchor |
| @serial | Describe a serialization attribute | @serial description |
| @serialData | Describe the data written through the writeObject() and writeExternal() methods | @serialData description |
| @serialField | Describe an ObjectStreamField component | @serialField name type description |
| @since | Mark when a specific change is introduced | @since release |
| @throws | Same as @exception tag. | The @throws tag has the same meaning as the @exception tag. |
| {@value} | Displays the value of a constant, which must be a static property. | Displays the value of a constant, which must be a static field. |
| @version | Specify the version of the class | @version info |
Documentation comments
After the opening /**, the first line or lines are about classes, variables and methods After the main description.
, you can include one or more @ tags of any kind. Each @ tag must be at the beginning of a new line or immediately followed by an asterisk (*) at the beginning of a line.
Multiple tags of the same type should be grouped together. For example, if you have three @see tags, place them one after the other.
The following is an example of a class description comment:
/*** This class draws a bar chart. * @author Zara Ali * @version 1.2 */
What does javadoc output?
The javadoc tool takes the source code of your Java program as input and outputs something containing HTML file for your program comments.
The information for each class will be in a separate HTML file. Javadoc can also output inherited tree structures and indexes.
Since the implementation of javadoc is different, the work may also be different. You need to check the version and other details of your Java development system and choose the appropriate Javadoc version.
Example
The following is a simple example of using description comments. Notice that each comment precedes the item it describes.
After being processed by javadoc, the comments of the SquareNum class will be found in SquareNum.html.
import java.io.*;
/**
* This class demonstrates documentation comments.
* @author Ayan Amhed
* @version 1.2
*/
public class SquareNum {
/**
* This method returns the square of num.
* This is a multiline description. You can use
* as many lines as you like.
* @param num The value to be squared.
* @return num squared.
*/
public double square(double num) {
return num * num;
}
/**
* This method inputs a number from the user.
* @return The value input as a double.
* @exception IOException On input error.
* @see IOException
*/
public double getNumber() throws IOException {
InputStreamReader isr = new InputStreamReader(System.in);
BufferedReader inData = new BufferedReader(isr);
String str;
str = inData.readLine();
return (new Double(str)).doubleValue();
}
/**
* This method demonstrates square().
* @param args Unused.
* @return Nothing.
* @exception IOException On input error.
* @see IOException
*/
public static void main(String args[]) throws IOException
{
SquareNum ob = new SquareNum();
double val;
System.out.println("Enter value to be squared: ");
val = ob.getNumber();
val = ob.square(val);
System.out.println("Squared value is " + val);
}
}As follows, use the javadoc tool to process the SquareNum.java file:
$ javadoc SquareNum.java Loading source file SquareNum.java... Constructing Javadoc information... Standard Doclet version 1.5.0_13 Building tree for all the packages and classes... Generating SquareNum.html... SquareNum.java:39: warning - @return tag cannot be used\ in method with void return type. Generating package-frame.html... Generating package-summary.html... Generating package-tree.html... Generating constant-values.html... Building index for all the packages and classes... Generating overview-tree.html... Generating index-all.html... Generating deprecated-list.html... Building index for all classes... Generating allclasses-frame.html... Generating allclasses-noframe.html... Generating index.html... Generating help-doc.html... Generating stylesheet.css... 1 warning $
