Comments in Java work like C++ with one important extension. Javadoc interprets special format comments to generate HTML man pages providing us with documentation for a project.
// Simple comment that extends to the end of the line
/*
Comment that includes all lines until
*/
/**
* javadoc comment. HTML modifiers can be put here.
* <PRE>
* paragraph formatting works
* so you can make comments more understandable
* and more clear. Javadoc ignores all the * in column 1
* </PRE>
*
* @author Fred Flintstone
* @param iColor If you want a color or something
* @return the answer is sent back.
* @exception java.lang.ArrayIndexOutOfBoundsException Thrown if
* you try to access an index outside of the size of the array.
* any comments after the @ is applied to the last @ line
*/
JAVADOC. Javadoc is a system of structured comments used to document
Java(tm) language APIs. The Java Development Kit comes with a program that
you can run over your source code to extract these comments. Javadoc is
not part of the Java programming language itself, but a documentation
convention that is widely used for documenting Java language APIs.
A simple example of Javadoc comments looks like this:
/**
* Class Sort implements some common sorting algorithms.
*/
public class Sort {
/**
* Sorts a Vector of objects.
*
* @param vec the vector
* @param dir true for ascending order, false for descending
* @exception SortArgumentException if vec is null
*/
public void sort_vec(Vector vec, boolean dir)
throws SortArgumentException
{
...
}
...
}
Javadoc comments start with /**, and use tags such as @param, @return, and
@exception to describe the workings of a method. Chapter 18 of the book
"The Java Language Specification" by James Gosling et al. describes
Javadoc conventions.
Extracted comments are processed into a set of HTML files for later perusal
by a web browser. Using Javadoc you can view the class hierarchy, an index
of all methods and fields, and the details of each class.
Javadoc makes the most accurate and reliable program description with the smallest programmer cooperation. Let's cooperate !