Java in a Nutshell, 5th Edition

Java Documentation Comments

Most ordinary comments within Java code explain the implementation details of that code. By contrast, the Java language specification defines a special type of comment known as a doc comment that serves to document the API of your code. A doc comment is an ordinary multiline comment that begins with /** (instead of the usual /*) and ends with */. A doc comment appears immediately before a type or member definition and contains documentation for that type or member. The documentation can include simple HTML formatting tags and other special keywords that provide additional information. Doc comments are ignored by the compiler, but they can be extracted and automatically turned into online HTML documentation by the javadoc program. (See Chapter 8 for more information about javadoc.) Here is an example class that contains appropriate doc comments:

/** * This immutable class represents <i>complex numbers</i>. * * @author David Flanagan * @version 1.0 */ public class Complex { /** * Holds the real part of this complex number. * @see #y */ protected double x; /** * Holds the imaginary part of this complex number. * @see #x */ protected double y; /** * Creates a new Complex object that represents the complex number x+yi. * @param x The real part of the complex number. * @param y The imaginary part of the complex number. */ public Complex(double x, double y) { this.x = x; this.y = y; } /** * Adds two Complex objects and produces a third object that represents ...