Java支持三种类型的注释。前两个是//和/**/。第三类被称为文档注释。它是从字符序列/*，并用*/结束。

文档注释允许嵌入程序的信息到程序本身。然后，可以使用javadoc工具来提取信息，并把它放到一个HTML文件。

文档注释使它方便地记录程序。

javadoc标签：

javadoc工具识别以下标记：

标签	描述	实例
@author	Identifies the author of a class.	@author description
@deprecated	Specifies that a class or member is deprecated.	@deprecated description
{@docRoot}	Specifies the path to the root directory of the current documentation	Directory Path
@exception	Identifies an exception thrown by a method.	@exception exception-name explanation
{@inheritDoc}	Inherits a comment from the immediate superclass.	Inherits a comment from the immediate surperclass.
{@link}	Inserts an in-line link to another topic.	{@link name text}
{@linkplain}	Inserts an in-line link to another topic, but the link is displayed in a plain-text font.	Inserts an in-line link to another topic.
@param	Documents a method's parameter.	@param parameter-name explanation
@return	Documents a method's return value.	@return explanation
@see	Specifies a link to another topic.	@see anchor
@serial	Documents a default serializable field.	@serial description
@serialData	Documents the data written by the writeObject( ) or writeExternal( ) methods	@serialData description
@serialField	Documents an ObjectStreamField component.	@serialField name type description
@since	States the release when a specific change was introduced.	@since release
@throws	Same as @exception.	The @throws tag has the same meaning as the @exception tag.
{@value}	Displays the value of a constant, which must be a static field.	Displays the value of a constant, which must be a static field.
@version	Specifies the version of a class.	@version info

文档注释：

之后开始/ **，第一行或行变得类，变量或方法的主要描述。

在此之后，可以包括一个不同的@标记以上。每一个@标记必须在开始一个新行的开头或跟随一个星号（*），即在一行的开头。

同一类型的多个标签应该被组合在一起。例如，如果有三个@标记，把它们一个接一个。

下面是一类文档注释的例子：

/**
* This class draws a bar chart.
* @author Zara Ali
* @version 1.2
*/

什么javadoc输出？

javadoc程序需要输入Java程序的源文件，输出包含该程序的文档多个HTML文件。

有关每个类信息将在其自己的HTML文件。 Java实用程序的javadoc也将输出一个索引和一个层次树。其他HTML文件可以生成。

由于javadoc中的不同实现可能有不同的工作，需要检查同伴的Java开发系统特定于版本的详细信息的说明。

例子：

下面是一个使用文档注释的示例程序。请注意每个注释前面紧邻，它描述了项目的方式。

由javadoc的处理后，对SquareNum类的文档将在SquareNum.htmll。

import java.io.*;

/**
* This class demonstrates documentation comments.
* @author Ayan Amhed 
* @version 1.2
*/
public class SquareNum {
   /**
   * This method returns the square of num.
   * This is a multiline description. You can use
   * as many lines as you like.
   * @param num The value to be squared.
   * @return num squared.
   */
   public double square(double num) {
      return num * num;
   }
   /**
   * This method inputs a number from the user.
   * @return The value input as a double.
   * @exception IOException On input error.
   * @see IOException
   */
   public double getNumber() throws IOException {
      InputStreamReader isr = new InputStreamReader(System.in);
      BufferedReader inData = new BufferedReader(isr);
      String str;
      str = inData.readLine();
      return (new Double(str)).doubleValue();
   }
   /**
   * This method demonstrates square().
   * @param args Unused.
   * @return Nothing.
   * @exception IOException On input error.
   * @see IOException
   */
   public static void main(String args[]) throws IOException
   {
      SquareNum ob = new SquareNum();
      double val;
      System.out.println("Enter value to be squared: ");
      val = ob.getNumber();
      val = ob.square(val);
      System.out.println("Squared value is " + val);
   }
}

现在，上述过程用javadoc工具作为SquareNum.java文件如下：

$ javadoc SquareNum.java
Loading source file SquareNum.java...
Constructing Javadoc information...
Standard Doclet version 1.5.0_13
Building tree for all the packages and classes...
Generating SquareNum.html...
SquareNum.java:39: warning - @return tag cannot be used
                      in method with void return type.
Generating package-frame.html...
Generating package-summary.html...
Generating package-tree.html...
Generating constant-values.html...
Building index for all the packages and classes...
Generating overview-tree.html...
Generating index-all.html...
Generating deprecated-list.html...
Building index for all classes...
Generating allclasses-frame.html...
Generating allclasses-noframe.html...
Generating index.html...
Generating help-doc.html...
Generating stylesheet.css...
1 warning
$

可以检查所有生成的文档在这里： SquareNum.