The comments that can be recognized by the javadoc tool must be placed between /** and */. Besides normal text, in the block of /** and */, there are some special tags that can be recognized by the javadoc tool. The table below summarizes these tags.
| Tag | Description | Example |
|---|---|---|
| @author | The author tag allows you to specify the information about the author. | @author Dara Yuk |
| @deprecated | This tag specifies that a class or method is deprecated in the current version. | @deprecated Deprecated |
| @exception | This tag is used to specify the type of exception to be thrown. | @exception IOException |
| {@link} | This tag is used to specify the in-line link to other page. | See the {@link <a href="JCalc.htm">JCalc</a>} |
| @param | This tag specifies the parameter of a method. | @param a |
| @return | This tag allows you to specify the return value of a method. | @return sum |
| @see | You can use this tag to provide a link to other topic or page. This link will shown at the "See Also" section of the page. | @see <a href="Jtutorial.html">Java Tutorial</a> |
| @serial | This tag specifies the default serial field. You can describe the field and its possible values. The information about this tag will be shown in the Serial Form page. | @serial The PI field |
| @since | You will use this tag to spcify the version of your software when a specific change was introduced. | @since 1.6 |
| {@value} | You will use this tag to display the value of a constant field. | The value of this field is {@value}. |
| @version | This tag will be used to specify the current version of your software. | @version 1.0 |
For example, you have the JCalc class that is a simple calculator class. It contains twelve methods that can be used to add, subtract, multiply, and divide integer and floating-pointer numbers.
/**
* This is the JCalc class. It has twelve methods that can be called to add, subtract, multiply,
* and divide floating-point numbers. See the {@link <a href="index.html">JCalc</a>}.
* @author Dara Yuk
* @version 1.0
*
*/
public class JCalc{
/**
* The value of the constant is {@value}.
*/
public static final double PI=Math.PI;
public static void main(String[] args){
}
/**
* This method adds two integer values a and b.
* @param a
* @param b
* @return a+b
* @see <a href="JavaTutorial.html">Java Tutorial</a>
*/
public int sum(int a,int b){
return(a+b);
}
/**
* This method adds two float values a and b.
* @param a
* @param b
* @return a+b
*/
public float sum(float a,float b){
return(a+b);
}
/**
* This method adds double values a and b.
* @param a
* @param b
* @return a+b
*/
public double sum(double a,double b){
return(a+b);
}
/**
* This method subtracts b from a. The parameters a and b are integer.
* @param a
* @param b
* @return a-b
*/
public int subtract(int a,int b){
return(a-b);
}
/**
* This method subtracts b from a. The parameters a and b are float.
* @param a
* @param b
* @return a-b
*/
public float subtract(float a,float b){
return(a-b);
}
/**
* This method subtracts b from a. The parameters a and b are double.
* @param a
* @param b
* @return a-b
*/
public double subtract(double a,double b){
return(a-b);
}
/**
* This method multiplies a and b. The parameters a and b are integer.
* @param a
* @param b
* @return a*b
*/
public int multiply(int a,int b){
return(a*b);
}
/**
* This method multiplies a and b. The parameters a and b are float.
* @param a
* @param b
* @return a*b
*/
public float multiply(float a,float b){
return(a*b);
}
/**
* This method multiplies a and b. The parameters a and b are double.
* @param a
* @param b
* @return a*b
*/
public double multiply(double a,double b){
return(a*b);
}
/**
* This method divides a by b. The parameters a and b are integer.
* @param a
* @param b
* @return a/b
*/
public double divide(int a,int b){
return(a/b);
}
/**
* This method divides a by b. The parameters a and b are float.
* @param a
* @param b
* @return a/b
*/
public float divide(float a,float b){
return(a/b);
}
/**
* This method divides a by b. The parameters a and b are double.
* @param a
* @param b
* @return a/b
*/
public double divide(double a,double b){
return(a/b);
}
}
To create the document of the JCalc class, from the command prompt, enter the directory that contains the JCalc.java file and type the following command:
D:\eclipse\charts\Calculator\src>javadoc -d docs JCalc.java
While javadoc is processing the file, the messages below are displayed on the screen.
Loading source file JCalc.java...
Constructing Javadoc information...
Standard Doclet version 1.7.0_21
Building tree for all the packages and classes...
Generating docs\JCalc.html...
Generating docs\package-frame.html...
Generating docs\package-summary.html...
Generating docs\package-tree.html...
Generating docs\constant-values.html...
Generating docs\serialized-form.html...
Building index for all the packages and classes...
Generating docs\overview-tree.html...
Generating docs\index-all.html...
Generating docs\deprecated-list.html...
Building index for all classes...
Generating docs\allclasses-frame.html...
Generating docs\allclasses-noframe.html...
Generating docs\index.html...
Generating docs\help-doc.html...
The document pages will be generated in the src/docs folder.
