What is Javadoc? Most of the times people confuse it with the actual HTML documentation for the Java code. This is somewhat true but not entirely. Javadoc, itself is not the documentation, it is a tool from SUN Microsystem that helps you generate the documents.
How does it work? Javadoc allows developers to add documentation for a code in the java file itself in some specially formatted comments. The tool will read these comments and create a HTML document file.
Why do we use Javadoc? Why can’t we just create documents on our own? Well That is possible. Javadoc is there to make your life simpler as a developer. It helps you keep your code and documentation information in the same file. Just imagine if you are keeping the documentation separately, everytime you make a change in code, you ill need to modify the documentation also. What if someone misses it? If it is in the same file it is easier to maintain and hard to miss. Most importantly, you are not writing the whole documentation, but just adding some quick comments which will be interpreted by the Javadoc tool. Lot more easier and faster than actually writing the documentation.
How to implement it? Simple, just add some specially formatted comments in your code
Class Level comments
@author : Author of the class @version : automatically provide accurate version and date updates. @since : Describes when this functionality has first existed.
Method Level
@param : method or constructor argument names and description @return : What does your method returns @throws : Does this method throw an exception @deprecated : Describes an outdated method.
General Commets
@see : Adds 'See also' entry @link : Adds an inline link with a label for users of your API documentation
The final code will look something like
import java.util.ArrayList;
/**
* This is a Java Class to find anagrams. Any class level description goes here
*
* @author kamal
* @version 1.0
* @since 21-Sep-2011
*/
public class test{
/**
* This is the main method method
*
* use {@link #findAnagrams(String)}
* @param str
* Any param description goes here
*/
public static void main(String str[])
{
try
{
String finalString="TestString";
test t =new test();
t.findAnagrams(finalString);
}
catch(Exception e) {
e.printStackTrace();
}
}
/**
* This is another method and we will add the description here
*
* @param input
* Any param description goes here
* @return
* @throws NullPointerException
*/
private ArrayList findAnagrams(String input) throws NullPointerException
{
ArrayList retList=new ArrayList();
if(input.equals("")) throw new NullPointerException();
printAnagrams(retList, "",input);
return retList;
}
/**
* Yet another method description goes here
*
* @param retList
* @param prefix
* @param word
*/
public void printAnagrams( ArrayList retList, String prefix, String word) {
if(word.length() <= 1) {
retList.add(prefix + word);
} else {
for(int i = 0; i < word.length(); i++) {
String cur = word.substring(i, i + 1);
String before = word.substring(0, i); // letters before cur
String after = word.substring(i + 1); // letters after cur
printAnagrams(retList,prefix + cur, before + after);
}
}
}
}
and your javadoc comments will look like
