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
]sourceFile
1|packageName
1|@fileList
1sourceFile
2|packageName
2|@fileList
2 ...
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 *.java
Table 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. |
18.224.68.28