In software programming it is important to document the source code, because:

• you will have a clear picture of complex Java projects with many classes or modules;
• you will be able, later, to understand what was done so that you can modify, add or delete it.

For Java applications, documentation is usually supplied in HTML format in the form of archives or .chm files. For an efficient source code documentation , JavaDoc projects are generated automatically based on source code comments with a JDK (Java Development Kit) tool, javadoc.exe.

We have seen in Tutorial Java 6 – #2 Basic concepts (other topics presented in this tutorial can be found in Tutorial Java 6 – Contents) how to write comments in Java, but to generate JavaDoc documentation, source code comments must be defined according to certain rules:

• JavaDoc comment blocks begin with /**
• JavaDoc comment blocks ends with */;
• lines of JavaDoc comments begin, by convention, with *;
• during the generation of JavaDoc documentation, * or spaces from the beginning of the comment are ignored;
• comments are used to generate documentation for methods or classes;
• because the Javadoc documentation is in HTML format, the comments can contain HTML tags used to format the content (eg <br> to move onto the next line)
• there are some Javadoc tags for classes or methods special attributes:

@deprecated tags are used by the compiler to generate warnings. This concept, but at another level, is seen also in annotations (Java annotations) beginning with Java 5.0.

For efficiency, JavaDoc documentation can be generated using an IDE, NetBeans (right-click the project name and then choose Generate Javadoc ) or Eclipse (Tutorial Java 6 – #2.2 How to generate JavaDoc in Eclipse or NetBeans) without having to use javadoc.exe and the command line.

For the Java source code from MyClass.java file:

/**
 * Java class example
 * The class illustrates how to write comments used 
 * to generate JavaDoc documentation
 *
 * @author Catalin
 * @version 2.00, 23 Dec 2010
 */
public class MyClass {
     /**
     *
     * Simple method.
     * 

     * The method prints a received message on the Console 
     *
     * @param message String variable to be printed
     * @see MyClass
     * @deprecated
     * @since version 1.00
     */
    public void MyMethod(String message)
    {
        System.out.printf(message);
    }

     /**
     *
     * Simple method example.
     * The method prints a received message on the Console 
     *
     * @param message String variable to be printed
     * @since version 1.00
     */
    public void printMessage(String message)
    {
        System.out.printf(message);
    }
     /**
     *
     * Simple method example.
     * 

     * The methods adds 2 numbers and return the result
     *
     * @param val1 the first value
     * @param val2 the second value
     * @return sum between val1 and val2
     * @since version 2.00
     */
    public int add(int val1, int val2)
    {
       return val1+val2;
    }
}

By generating the JavaDoc in Netbeans (right-click the project name and then choose Generate Javadoc ) or in Eclipse (Tutorial Java 6 – #2.2 How to generate JavaDoc in Eclipse or NetBeans) it is obtained Javadoc documentation for the sample source code.

If you are using Eclipse for development, the IDE has features that allow automatic generation of JavaDoc comments for your classes or methods. If you write this method:

public int add2(int val1, int val2)
    {
       return val1+val2;
    }

then you can use Generate Element Comment (Alt + Shift + J) from the Source menu. It will automatically generate a block of comments:

    /**
     * @param val1
     * @param val2
     * @return
     */
    public int add2(int val1, int val2)
    {
       return val1+val2;
    }

Other topics presented in this Java tutorial can be found in Tutorial Java 6 – Contents.