Syntax
All of the javadoc commands occur only within /** comments. The comments end with */ as usual. There are two primary ways to use javadoc: embed HTML or use “doc tags.” Standalone doc tags are commands that start with a ‘@’ and are placed at the beginning of a comment line. (A leading ‘*’, however, is ignored.) Inline doc tags can appear anywhere within a javadoc comment and also start with a ‘@’ but are surrounded by curly braces.
There are three “types” of comment documentation, which correspond to the element the comment precedes: class, variable, or method. That is, a class comment appears right before the definition of a class; a variable comment appears right in front of the definition of a variable, and a method comment appears right in front of the definition of a method. As a simple example:
/** A class comment */
public class DocTest {
/** A variable comment */
public int i;
/** A method comment */
public void f() {}
}
Note that javadoc will process comment documentation for only public and protected members. Comments for private and package-access members (see Chapter 5) are ignored, and you’ll see no output. (However, you can use the -private flag to include private members as well.) This makes sense, since only public and protected members are available outside the file, which is the client programmer’s perspective. However, all class comments are included in the output.
The output for the preceding code is an HTML file that has the same standard format as all the rest of the Java documentation, so users will be comfortable with the format and can easily navigate your classes. It’s worth entering the preceding code, sending it through javadoc, and viewing the resulting HTML file to see the results.
