javadoc

Documentation
The Java language was designed to support the principles of information hiding and encapsulation. Java comes with a program called javadoc that will automatically extract the "interface" from a class definition, if you have followed the guidelines below. The result of running javadoc is a set of html files.

Comment conventions

Comments should immediately precede a public class definition, a public method, or other public item.
The comment must be a block comment (using /* and */ to surround comment lines) and the opening /* must contain an extra *.
Line comments (//) are not extracted by javadocs. They are appropriate for comments that would be important to anyone trying to read and understand the body of your code (i.e., a programmer maintaining your code).
Any general information that a user of the class or method might need to know is appropriate to include in the javadoc style comments.
The javadoc conventions include a number of special parameters that may be used. These are called @tags. Each @tag should be on a separate line, and all the @tags should be listed after any general comments. The @tags are optional, but if included should be in the same order as listed below:

@param Parameter_name Parameter_Description. Each parameter should be listed with its own @param tag, and the order should match the order in the function header.
@return Description_of_value_returned
@throws Exception_type Explanation
@deprecated.
@see Package_Name.Class_Name
@author Author. If multiple authors, use multiple @author lines.
@version Version_information

Example:

	/**
	 * Main Method of the HelloWorld program. This program
	 * outputs simple messages to the terminal in which it
	 * is running.
	 *
	 * @param args All command line arguments are ignored
	 */

Using javadoc in Eclipse:

To create comments in Eclipse, put your cursor on the beginning of a method and press Shift-Alt-J (or select Source-Add Comment). The skeleton for your javadoc comments will be provided and you can fill in the details.

To generate the html files, select Project->Generate Javadoc. If it's the first time, you may need to tell Eclipse where the javadoc.exe file exists (it should be located in the bin directory of your jdk, e.g., c:\jdk1.5.0\bin\javadoc.exe). Then select the file or files for which you want comments generated. NOTE: this javadoc function will generate html files even if no comments have been inserted, but there will be no details about any of the functions.