Documentation in Java

In this tutorial, you will learn to do documentation of your Java programs. Java comes with a powerful tool called javadoc. This tool allows Java developer easily to create documentation of their programs. The javadoc tool extracts your comments embedded in the source code, constant fields, class name, methods and outputs these information in html files.
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.