Javadoc Tutorial
Introduction
- Javadoc is a tool that generates html documentation (similar to the reference pages at java.sun.com) from Javadoc comments in the code. In this tutorial we will go over how to write basic Javadoc comments and how to use features of Javadoc to generate html documentation.
Javadoc Comments
- Javadoc recognizes special comments /** .... */ which are highlighted blue by default in Eclipse (regular comments // and /* ... */ are highlighted green).
- Javadoc allows you to attach descriptions to classes, constructors, fields, interfaces and methods in the generated html documentation by placing Javadoc comments directly before their declaration statements.
- Here's an example using Javadoc comments to describe a class, a field and a constructor:
/** Class Description of MyClass */
public class MyClass
{ /** Field Description of myIntField */
public int myIntField;
/** Constructor Description of MyClass() */
public MyClass()
{ // Do something ... }
}
Javadoc Tags
- Tags are keywords recognized by Javadoc which define the type of information that follows.
- Tags come after the description (separated by a new line).
- Here are some common pre-defined tags:
- @author [author name] - identifies author(s) of a class or interface.
- @version [version] - version info of a class or interface.
- @param [argument name] [argument description] - describes an argument of method or constructor.
- @return [description of return] - describes data returned by method (unnecessary for constructors and void methods).
- @exception [exception thrown] [exception description] - describes exception thrown by method.
- @throws [exception thrown] [exception description] - same as @exception.
- Here's an example with tags:
import java.io.*;
/**
* <h1>Add Two Numbers!</h1>
* The AddNum program implements an application that
* simply adds two given integer numbers and Prints
* the output on the screen.
* <p>
* <b>Note:</b> Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
*
* @author Zara Ali
* @version 1.0
* @since 2014-03-31
*/
public class AddNum {
/**
* This method is used to add two integers. This is
* a the simplest form of a class method, just to
* show the usage of various javadoc Tags.
* @param numA This is the first paramter to addNum method
* @param numB This is the second parameter to addNum method
* @return This returns sum of numA and numB.
*/
public int addNum(int numA, int numB) {
return numA + numB;
}
/**
* This is the main method which makes use of addNum method.
* @param args Unused.
* @exception IOException On input error.
* @see IOException
*/
public static void main(String args[]) throws IOException
{
AddNum obj = new AddNum();
int sum = obj.addNum(10, 20);
System.out.println("Sum of 10 and 20 is :" + sum);
}
}
Javadoc References
- Javadoc is a powerful tool with many more features, for more information check out the following links: