Implementing Classes - Java Concepts - page 123

describing the return value. You omit the @param tag for methods that have no
parameters, and you omit the @return tag for methods whose return type is void .

Use documentation comments to describe the classes and public methods of your
programs.

The javadoc utility copies the first sentence of each comment to a summary table
in the HTML documentation. Therefore, it is best to write that first sentence with
some care. It should start with an uppercase letter and end with a period. It does not
have to be a grammatically complete sentence, but it should be meaningful when it is
pulled out of the comment and displayed in a summary.

Here are two typical examples.

/**
Withdraws money from the bank account.
@param amount the amount to withdraw
*/
public void withdraw(double amount)
{
implementationÏfilled in later
}
/**
Gets the current balance of the bank account.
@return the current balance
*/
public double getBalance()
{
implementationÏfilled in later
}

90
91

The comments you have just seen explain individual methods. Supply a brief
comment for each class, explaining its purpose. The comment syntax for class
comments is very simple: Just place the documentation comment above the class.

/**
A bank account has a balance that can be changed
by
deposits and withdrawals.
*/
public class BankAccount
{