javadoc

 javadoc工具可以为以下条目生成注释文档：

• Packages

• Public classes and interfaces

• Public and protected methods

• Public and protected fields

注释为包含在/** 和 */之间，可以为任意格式的文本，当然也可以包含html的标签，如使用<em></em>以示强调等，但是应该避免使用标题标签如<h1>和划线标签如<hr>等，因为这些标签会影响文档的格式。

The first sentence of the free-form text should be a summary statement. The javadoc utility

automatically generates summary pages that extract these sentences

NOTE: If your comments contain links to other files such as images (for example, diagrams

or images of user interface components), place those files into a subdirectory of the

directory containing the source file named doc-files. The javadoc utility will copy the docfiles

directories and their contents from the source directory to the documentation directory.

You need to use the doc-files directory in your link, such as <img src="doc-files/

uml.png" alt="UML diagram"/>.

Class Comments

The class comment must be placed after any import statements, directly before the class

definition.

Method Comments

Each method comment must immediately precede the method that it describes. In addition

to the general-purpose tags, you can use the following tags:

• @param variable description

This tag adds an entry to the “parameters” section of the current method. The

description can span multiple lines and can use HTML tags. All @param tags for one

method must be kept together.

• @return description

This tag adds a “returns” section to the current method. The description can span

multiple lines and can use HTML tags.

• @throws class description

This tag adds a note that this method may throw an exception. Exceptions are the

topic of Chapter 11.

Field Comments

You only need to document public fields—generally that means static constants. For

example:

/**

* The "Hearts" card suit

*/

public static final int HEARTS = 1;