Java Reference
In-Depth Information
pages” are to Unix, or what Windows Help is to Windows applications: it is a standard
format that everybody expects to find and knows how to use. Learn it. Use it. Write it. Live
long and prosper (well, perhaps that's not guaranteed). But all that HTML documentation
that you learned from writing Java code, the complete reference for the JDK—did you think
they hired dozens of tech writers to produce it? Nay, that's not the Java way. Java's deve-
lopers wrote the documentation comments as they went along, and when the release was
made, they ran javadoc on all the zillions of public classes and generated the documentation
bundle at the same time as the JDK. You can, should, and really must do the same when you
are preparing classes for other developers to use.
All you have to do to use javadoc is to put special “javadoc comments” into your Java source
files. These are similar to multiline Java comments, but begin with a slash and
two
stars, and
end with the normal star-slash. Javadoc comments must appear immediately before the defin-
ition of the class, method, or field that they document; if placed elsewhere, they are ignored.
A series of keywords, prefixed by the at sign (
@
), can appear inside doc comments in certain
contexts. Some are contained in braces (“{…}”). The keywords as of Java 8 are listed in
