Javadoc简介

Javadoc是一项文档生成技术，用于从Java代码生成HTML文档。
结构：Javadoc包含在文档注释中， 形如 /** documentation */

• 第一段是描述性的文字，是对所注释的对象的描述
• 其他描述性标签，包括 @param @return @throws @see @author @version @since

类注释预览

// import statements

/**
 * @author      Firstname Lastname <address @ example.com>
 * @version     1.6          (current version number of program)
 * @since       1.2          (the version of the package this class was first added to)
 */
public class Test {
    // class body
}

Javadoc和被注释的元素之间不能有新行
import语句应当在任何注释之前
方法注释预览

/**
 * Short one line description.                           (1)
 * <p>
 * Longer description. If there were any, it would be    (2)
 * here.
 * <p>
 * And even more explanations to follow in consecutive
 * paragraphs separated by HTML paragraph breaks.
 *
 * @param  variable Description text text text.          (3)
 * @return Description text text text.
 */
public int methodName (...) {
    // method body with a return statement
}

包含三部分： 第一部分是单行的简短、清晰的描述；第二部分是详细的解释，可以使用HTML标记；第三部分是描述性标签
变量注释预览

/**
 * Description of the variable here.
 */
private int debug = 0;

变量注释和方法注释一样，除了其没有第三部分以外。
应当一条语句定义多个变量

/**
 * The horizontal and vertical distances of point (x,y)
 */
public int x, y;      // AVOID

这是因为Javadoc会为每个单独的变量生成一份注释的拷贝。
Javadoc描述性标签列表

Tag & Parameter	Usage	Applies to	Since
@author	John Smith Describes an author.	Class, Interface, Enum
@version	version Provides software version entry. Max one per Class or Interface.	Class, Interface, Enum
@since	since-text Describes when this functionality has first existed.	Class, Interface, Enum, Field, Method
@see	reference Provides a link to other element of documentation.	Class, Interface, Enum, Field, Method
@param	name description Describes a method parameter.	Method
@return	description Describes the return value.	Method
@exception	classname description
@throws	classname description Describes an exception that may be thrown from this method.	Method
@deprecated	description Describes an outdated method.	Class, Interface, Enum, Field, Method
{@inheritDoc}	Copies the description from the overridden method.	Overriding Method	1.4.0
{@link reference}	Link to other symbol.	Class, Interface, Enum, Field, Method
{@value #STATIC_FIELD}	Return the value of a static field.	Static Field	1.4.0
{@code literal}	Formats literal text in the code font. It is equivalent to <code>{@literal}</code>.	Class, Interface, Enum, Field, Method	1.5.0
{@literal literal}	Denotes literal text. The enclosed text is interpreted as not containing HTML markup or nested javadoc tags.	Class, Interface, Enum, Field, Method	1.5.0

例子

/**
 * Validates a chess move.
 *
 * Use {@link #doMove(int theFromFile, int theFromRank, int theToFile, int theToRank)} to move a piece.
 *
 * @param theFromFile file from which a piece is being moved
 * @param theFromRank rank from which a piece is being moved
 * @param theToFile   file to which a piece is being moved
 * @param theToRank   rank to which a piece is being moved
 * @return            true if the move is valid, otherwise false
 */
boolean isValidMove(int theFromFile, int theFromRank, int theToFile, int theToRank) {
    // ...body
}

/**
 * Moves a chess piece.
 *
 * @see java.math.RoundingMode
 */
void doMove(int theFromFile, int theFromRank, int theToFile, int theToRank)  {
    // ...body
}

参考
https://en.wikipedia.org/wiki/Javadoc

JDiff和doclet及taglet