Java Documentation Comments

Java supports three comment styles:

  • Single-line comments
  • Multi-line comments
  • Documentation comments

The first two are respectively//and/* */, the third type is called documentation comments, which starts/**with the opening delimiter and ends*/with the closing delimiter.

You can refer to the following for the first two comment types:Java Comments

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

You can use the javadoc tool to generate the information and output it to an HTML file.

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

javadoc Tags

The javadoc tool recognizes the following tags:

Tag Description Example
@author Identifies the author of a class @author description
@deprecated Indicates a deprecated class or member @deprecated description
{@docRoot} Indicates the path to the current document root directory Directory Path
@exception Documents an exception thrown by a class @exception exception-name explanation
{@inheritDoc} Inherits a comment from the immediate parent class Inherits a comment from the immediate surperclass.
{@link} Inserts a link to another topic {@link name text}
{@linkplain} Inserts a link to another topic, but the link is displayed in plain text font Inserts an in-line link to another topic.
@param Describes a method parameter @param parameter-name explanation
@return Describes the return value type @return explanation
@see Specifies a link to another topic @see anchor
@serial Describes a serialization property @serial description
@serialData Describes data written through the writeObject( ) and writeExternal( ) methods @serialData description
@serialField Describes an ObjectStreamField component @serialField name type description
@since Marks when a specific change is 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 attribute. 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 are the main description of the class, variable, or method.

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

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

Below is an example of a class comment:

/*** This class draws a bar chart * @author example * @version 1.2 */

What javadoc Outputs

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

Each class's information will be in a separate HTML file. javadoc can also output inheritance tree structures and indexes.

Since javadoc implementations differ, the output may also differ. You need to check details such as the version of your Java development system and choose the appropriate Javadoc version.

Example

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

After being processed by javadoc, the SquareNum class comment will be found in SquareNum.html.

SquareNum.java file code:

import java.io.*; /** * This class demonstrates documentation comments * @author Ayan Amhed * @version 1.2 */ public class SquareNum { /** * This method returns the square of num. * This is a multiline description. You can use * as many lines as you like. * @param num The value to be squared. * @return num squared. */ public double square(double num) { return num * num; } /** * This method inputs a number from the user. * @return The value input as a double. * @exception IOException On input error. * @see IOException */ 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 method demonstrates square(). * @param args Unused. * @return Nothing. * @exception IOException On input error. * @see IOException */ 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
$
Other Extensions