Java Reference
In-Depth Information
An Example of Documentation Comments
Listing B-1 has the source code for a
Calc
class. It is a trivial class. Its purpose is only to demonstrate how to write
documentation comments. It uses many of the tags, which we discussed earlier. Figure
B-1
shows the generated
HTML page (partially shown) for the
Calc
class documentation.
Listing B-1.
Calc Class Source Code with Documentation Comment
// Calc.java
package com.jdojo.utility;
/**
* A utility class to perform basic calculations on numbers.
* All methods in this class are <code>static</code>. It
* provides methods to perform addition, subtraction,
* multiplication and division.
*
* @author Kishori Sharan
* @since Version 1.0
*/
public final class Calc {
/**
* Stop someone from instantiating this class. This class is not
* meant for instantiation as all its methods are
* <code>static</code>.
*/
private Calc() {
}
/**
* Performs addition on two numbers. It returns the result of
* <code> n1 + n2 </code>as an <code>int</code>. If the result
* of <code>n1 + n2</code> exceeds the range of the
* <code>int</code> data type, it will not return the correct
* result. For bigger numbers, use {@link #add(long, long)}.
*
* @param n1 The first number
* @param n2 The second number
* @return Returns the value of <code>n1 + n2</code>
*/
public static int add(int n1, int n2) {
return n1 + n2;
}
/**
* Performs addition on two numbers. It returns the result of
* <code>n1 + n2</code> as a <code>long</code>.
*
* @param n1 The first number
* @param n2 The second number
* @return Returns the value of <code>n1 + n2</code>
*/
