Java Documentation

Java supports three types of comments:

Single-line comments
Multi-line comments
Documentation comments

The first two are // and /* */ respectively. The third type is called a documentation comment, which starts with /** and ends with */.

For the first two types of comments, you can refer to: Java Comments

Documentation comments allow you to embed information about your program within the program itself.

You can use the javadoc tool to generate this information and output it to HTML files.

Documentation comments make it more convenient for you to record information about your program.

javadoc Tags

The javadoc tool recognizes the following tags:

Tag	Description	Example
`@author`	Identifies the author of a class	`@author description`
`@deprecated`	Specifies a deprecated class or member	`@deprecated description`
`{@docRoot}`	Specifies the path to the current document root directory	Directory Path
`@exception`	Tags an exception thrown by a class	`@exception exception-name explanation`
`{@inheritDoc}`	Inherits a comment from the immediate superclass	Inherits a comment from the immediate superclass.
`{@link}`	Inserts an in-line link to another topic	`{@link name text}`
`{@linkplain}`	Inserts an in-line link to another topic, but displays in plain text font	Inserts an in-line link to another topic.
`@param`	Documents a method parameter	`@param parameter-name explanation`
`@return`	Documents the return value type	`@return explanation`
`@see`	Specifies a link to another topic	`@see anchor`
`@serial`	Documents a serializable field	`@serial description`
`@serialData`	Documents data written by the `writeObject()` and `writeExternal()` methods	`@serialData description`
`@serialField`	Documents an `ObjectStreamField` component	`@serialField name type description`
`@since`	Tags when a specific change was introduced	`@since release`
`@throws`	Same as the `@exception` tag.	The `@throws` tag has the same meaning as the `@exception` tag.
`{@value}`	Displays the value of a constant, which must be a static field.	Displays the value of a constant, which must be a static field.
`@version`	Specifies the version of a class	`@version info`

Documentation Comments

After the opening /**, the first line or lines provide the main description for the class, variable, or method.

After that, you can include one or more various @ tags. Each @ tag must start on a new line or immediately follow an asterisk * at the beginning of a line.

Multiple tags of the same type should be grouped together. For example, if you have three @see tags, you can place them one after another.

Below is an example of a stable comment for a class:

@author @version

What javadoc Outputs

The javadoc tool takes the source code of your Java program as input and outputs several HTML files containing your program's comments.

Information for each class is placed in its own HTML file. javadoc can also output an inheritance tree and an index.

Due to differences in javadoc implementations, the output may vary. You need to check the version details of your Java development system and choose the appropriate Javadoc version.

Example

Here is a simple example using documentation comments. Note that each comment is placed before the item it describes.

After processing with javadoc, the comments for the SquareNum class can be found in SquareNum.html.

SquareNum.java File Code:

import java.io.*;
/**
 * This class demonstrates documentation comments.
 * @author Zara
 * @version 1.0
 */
public class SquareNum {
    /**
     * This method returns the square of a number.
     * @param num The number to be squared.
     * @return The square of the input number.
     */
    public double square(double num) {
        return num * num;
    }
    /**
     * This method gets a number from the user.
     * @return The number entered by the user.
     * @throws IOException If an input error occurs.
     * @see java.io.BufferedReader
     */
    public double getNumber() throws IOException {
        InputStreamReader isr = new InputStreamReader(System.in);
        BufferedReader inData = new BufferedReader(isr);
        String str;
        str = inData.readLine();
        return (new Double(str)).doubleValue();
    }
    /**
     * This is the main method.
     * @param args Command line arguments (not used).
     * @throws IOException If an input error occurs.
     * @see SquareNum#getNumber()
     * @see SquareNum#square(double)
     */
    public static void main(String args[]) throws IOException {
        SquareNum ob = new SquareNum();
        double val;
        System.out.println("Enter value to be squared: ");
        val = ob.getNumber();
        val = ob.square(val);
        System.out.println("Squared value is " + val);
    }
}

As shown below, use the javadoc tool to process the SquareNum.java file:

$ javadoc SquareNum.java
Loading source file SquareNum.java...
Constructing Javadoc information...
Standard Doclet version 1.5.0_13
Building tree for all the packages and classes...
Generating SquareNum.html...
SquareNum.java:39: warning - @return tag cannot be used in method with void return type.
Generating package-frame.html...
Generating package-summary.html...
Generating package-tree.html...
Generating constant-values.html...
Building index for all the packages and classes...
Generating overview-tree.html...
Generating index-all.html...
Generating deprecated-list.html...
Building index for all classes...
Generating allclasses-frame.html...
Generating allclasses-noframe.html...
Generating index.html...
Generating help-doc.html...
Generating stylesheet.css...
1 warning
$

YouTip