Java 代碼中的大多數(shù)普通注釋都解釋了該代碼的實(shí)現(xiàn)細(xì)節(jié)。相反，Java 語言規(guī)范定義了一種特殊類型的注釋，稱為文檔注釋，用于記錄代碼的 API。

文檔注釋是一個(gè)普通的多行注釋，以/**(而不是通常的/*)開頭并以*/結(jié)尾. 文檔注釋出現(xiàn)在類、接口、方法或字段定義之前，并包含該類、接口、方法或字段的文檔。文檔可以包括簡單的 HTML 格式標(biāo)記和其他提供附加信息的特殊關(guān)鍵字。文檔注釋會(huì)被編譯器忽略，但它們可以被javadoc 程序提取并自動(dòng)轉(zhuǎn)換為在線 HTML 文檔。這是一個(gè)包含適當(dāng)文檔注釋的示例類： docstore.mik.ua/orelly/java-ent/jnut/ch07_03.htm

/** 
* This immutable class represents complex 
* numbers. * 
* @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 
* their sum. 
* @param c1 A Complex object 
* @param c2 Another Complex object 
* @return A new Complex object that represents the sum of 
* c1 and 
* c2. 
* @exception java.lang.NullPointerException 
* If either argument is null. 
*/ public Complex add(Complex c1, Complex c2) { return new Complex(c1.x + c2.x, c1.y + c2.y); } } docstore.mik.ua/orelly/java-ent/jnut/ch07_03.htm