A documentation comment is delimited by /** and */. You can comment
Classes
Methods
Instance variables
Each comment is placed immediately above the feature it documents.
Each /** ... */ documentation comment contains introductory text followed by tagged documentation. A tag starts with an @ character, such as @author or @param. Tags are summarized in Table 1. The first sentence of the introductory text should be a summary statement. The javadoc utility automatically generates summary pages that extract these sentences.
Table H.1. Common javadoc Tags
Tag | Description |
|---|---|
| A parameter of a method. Use a separate tag for each parameter. |
| The return value of a method. |
| An exception that a method may throw. Use a separate tag for each exception. |
| A feature that remains for compatibility but that should not be used for new code. |
#methodName
| A reference to a related documentation entry. |
| The author of a class or interface. Use a separate tag for each author. |
| The version of a class or interface. |
You can use HTML tags such as em for emphasis, code for a monospaced font, img for images, ul for bulleted lists, and so on.
Here is a typical example. The summary sentence (in color) will be included with the method summary.
/**
Withdraws money from the bank account. Increments the
transaction count.
@param amount the amount to withdraw
@return the balance after the withdrawal
@throws IllegalArgumentException if the balance is not sufficient
*/
public double withdraw(double amount)
{
if (balance - amount < minimumBalance)
throw new IllegalArgumentException();
balance = balance - amount;
transactions++;
return balance;
}To extract the comments, run the javadoc program:
javadoc [options]sourceFile1|packageName1|@fileList1sourceFile2|packageName2|@fileList2 ...
See the documentation of the javac command in Appendix F for an explanation of file lists. Commonly used options are summarized in Table 2.
To document all files in the current directory, use (all on one line)
javadoc -link http://java.sun.com/javase/7/docs/api
-d docdir *.javaTable H.2. Common javadoc Command Line Options
Option | Description |
|---|---|
| Link to another set of Javadoc files. You should include a link to the standard library documentation, either locally or at |
| Store the output in directory. This is a useful option, because it keeps your current directory from being cluttered up with |
| Look for classes on the specified paths, overriding the |
| Look for source files on the specified paths. If not specified, source files are searched in the class path. |
| Include author, version information in the documentation. This information is omitted by default. |