以下内容引用自http://wiki.jikexueyuan.com/project/java/documentation.html：
Java语言支持三种注释形式：
| 注释 | 描述 |
|---|---|
| /*text*/ | 编译器忽略/*到*/的所有东西 |
| //text | 编译器忽略从//到一行末尾的所有东西 |
| /** documentation */ |
这是文档注释并且通常而言它被叫做doc comment。JDK javadoc工具当准备自动准备生成文件时使用doc comment |
一、什么是Javadoc？
Javadoc是JDK附带的一个工具，它被用来生成从需要预定义格式的文档的Java源代码至HTML格式的Java代码文件。
以下是一个简单的例子，其中红色部分代表Java注释：
/** * The HelloWorld program implements an application that * simply displays "Hello World!" to the standard output. * * @author Zara Ali * @version 1.0 * @since 2014-03-31 */ public class HelloWorld { public static void main(String[] args) { // Prints Hello, World! on standard output. System.out.println("Hello World!"); } }
可以将需要的HTM 标签包括在描述部分内，比如，下面的例子利用<h1>...</h1>来定义头部和<p>被用来创建段落间隔：
/** * <h1>Hello, World!</h1> * The HelloWorld program implements an application that * simply displays "Hello World!" to the standard output. * <p> * Giving proper comments in your program makes it more * user friendly and it is assumed as a high quality code. * * * @author Zara Ali * @version 1.0 * @since 2014-03-31 */ public class HelloWorld { public static void main(String[] args) { // Prints Hello, World! on standard output. System.out.println("Hello World!"); } }
二、Javadoc标签
Javadoc标签是Javadoc认可的关键字，它定义了下面信息的类型。
Javadoc工具认可下面的标签：
| 标签 | 描述 | 语法 | ||
|---|---|---|---|---|
| @author | 添加类的作者 | @author name-text | ||
| {@code} | 不把文本转换成HTML标记和嵌套的Java标签而用代码字体展示它 | {@code text} | ||
| {@docRoot} | 表示从任何生成页面到生成文档的根目录的相对路径 | {@docRoot} | ||
| @deprecated | 添加一个注释暗示API应该不再被使用 | @deprecated deprecated-text | ||
| @exception | 用类名和描述文本给生成的文档添加一个副标题 | @exception class-name description | ||
| {@inheritDoc} | 从最近的可继承的类或可实现的接口继承注释 | Inherits a comment from the immediate surperclass. | ||
| {@link} | 用指向特定的包，类或者一个引用类的成员名的文档的可见文本标签插入在线链接 | {@link package.class#member label} | ||
| {@linkplain} | 和{@link}相同，除了链接的标签用纯文本标示而不是代码字体 | {@linkplain package.class#member label} | ||
| @param | 给“参数”区域添加一个有特定参数名且后跟着特定描述的参数 | @param parameter-name description | ||
| @return | 添加一个有描述文本的“Returns”区域 | @return description | ||
| @see | 添加带有链接或者指向引用的文本入口的标题“See Also” | @see reference | ||
| @serial | 在默认的序列化字段的文本注释中使用 | @serial field-description | include | exclude |
| @serialData | 记录由writeObject( )或writeExternal( )方法所写的数据 | @serialData data-description | ||
| @serialField | 记录一个ObjectStreamField成分 | @serialField field-name field-type field-description | ||
| @since | 给生成的文档添加一个带有特定since文本的"Since"标题 | @since release | ||
| @throws | @throw和@exception标签是同义词 | @throws class-name description | ||
| {@value} | 当{@value}被用在一个静态字段的文本注释中，它展示了那个常量的值 | {@value package.class#field} | ||
| @version | 当-version选项被使用时用特定的version文本给生成的文本添加一个“Version”副标题 | @version version-text |
示例：
下面的程序使用一些重要的标签来做文档注释。可以基于需求利用其它的标签。
关于AddNum类的文档将由HTML文件AddNum.html创建，但是同时一个名为index.html的主文件也将被创建。
import java.io.*; /** * <h1>Add Two Numbers!</h1> * The AddNum program implements an application that * simply adds two given integer numbers and Prints * the output on the screen. * <p> * <b>Note:</b> Giving proper comments in your program makes it more * user friendly and it is assumed as a high quality code. * * @author Zara Ali * @version 1.0 * @since 2014-03-31 */ public class AddNum { /** * This method is used to add two integers. This is * a the simplest form of a class method, just to * show the usage of various javadoc Tags. * @param numA This is the first paramter to addNum method * @param numB This is the second parameter to addNum method * @return int This returns sum of numA and numB. */ public int addNum(int numA, int numB) { return numA + numB; } /** * This is the main method which makes use of addNum method. * @param args Unused. * @return Nothing. * @exception IOException On input error. * @see IOException */ public static void main(String args[]) throws IOException { AddNum obj = new AddNum(); int sum = obj.addNum(10, 20); System.out.println("Sum of 10 and 20 is :" + sum); } }
现在，处理使用Javadoc的AddNum.java文件：
$ javadoc AddNum.java Loading source file AddNum.java... Constructing Javadoc information... Standard Doclet version 1.7.0_51 Building tree for all the packages and classes... Generating /AddNum.html... AddNum.java:36: 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... 1 warning $
如果正在使用JDK 1.7那么Javadoc不生成stysheet.css，所以建议从http://docs.oracle.com/javase/7/docs/api/stylesheet.css下载并使用标准的stylesheet。