本章节将解释如何利用 Javadoc 生成有用的 Java 代码文档。
Java 文档可以通过 Javadoc 工具生成，默认情况下它生成的是 HTML 4.0 格式的文档。从 Java 9 开始，可以通过在命令行参数中使用 -html5 选项来生成 HTML 5 格式的文档。
什么是 Javadoc？
Javadoc 是随 JDK 发布的一个工具，用于从 Java 源代码中生成 HTML 格式的文档，前提是源代码中的注释需要遵循预定义的格式。
示例
以下是一个简单的例子，其中 /*….*/ 之间的行是 Java 多行注释。同样，以 // 开头的一行是 Java 单行注释。
public class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello World!");
}
}
输出结果将是 Hello World!。
可以在描述部分包含所需的 HTML 标签。例如，下面的例子使用了 <h1>....</h1> 作为标题，并且 <p> 用来创建段落断行：
示例
public class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello World!");
}
}
输出结果同样是 Hello World!。
Javadoc 标签
Javadoc 工具识别以下标签：
| 标签 |
描述 |
语法 |
@author |
添加类的作者信息。 |
@author name-text |
{@code} |
显示文本为代码字体而不解释为 HTML 标记或嵌套 Javadoc 标签。 |
{@code text} |
{@docRoot} |
表示从任意生成页面到生成文档根目录的相对路径。 |
{@docRoot} |
@deprecated |
添加注释表明此 API 不应再使用。 |
@deprecated deprecatedtext |
@exception |
在生成的文档中添加“Throws”小节，包含类名和描述文本。 |
@exception class-name description |
{@inheritDoc} |
继承最近可继承的类或实现接口的注释。 |
从直接的超类继承注释。 |
{@link} |
插入指向指定包、类或引用类成员名称的内联链接。 |
{@link package.class#member label} |
{@linkplain} |
与 {@link} 相同，但链接标签以普通文本形式显示而非代码字体。 |
{@linkplain package.class#member label} |
@param |
在“参数”部分添加带有指定参数名及其描述的参数。 |
@param parameter-name description |
@return |
在“返回”部分添加描述文本。 |
@return description |
@see |
添加指向参考的“另见”标题与链接或文本条目。 |
@see reference |
@serial |
用于默认序列化字段的文档注释中。 |
`@serial field-description |
@serialData |
文档化由 writeObject() 或 writeExternal() 方法写入的数据。 |
@serialData data-description |
@serialField |
文档化 ObjectStreamField 组件。 |
@serialField field-name field-type field-description |
@since |
向生成的文档添加带有指定版本文本的“自从”标题。 |
@since release |
@throws |
@throws 和 @exception 标签是同义词。 |
@throws class-name description |
{@value} |
当 {@value} 用在静态字段的文档注释中时，显示该常量的值。 |
{@value package.class#field} |
@version |
使用 -version 选项时，向生成的文档添加带有指定版本文本的“版本”小节。 |
@version version-text |
示例 - 使用旧版 Java 文档
以下程序使用了几个重要的可用文档注释标签。你可以根据需要使用其他标签。
关于 AddNum 类的文档将以 HTML 文件 AddNum.html 的形式生成，同时还会生成一个名为 index.html 的主索引文件。
import java.io.*;
public class AddNum {
public int addNum(int numA, int numB) {
return numA + numB;
}
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);
}
}
编译并运行上述程序，将产生以下结果：
Sum of 10 and 20 is :30
现在，使用 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
$
可以在以下位置检查所有生成的文档：AddNum。如果你正在使用 JDK 1.7，则 Javadoc 生成的样式表可能不够好，因此建议下载并使用标准样式表 https://docs.oracle.com。
示例 - 使用新版 HTML5 格式 Java 文档
使用 JDK 9 的 Javadoc 工具与 -html5 标志生成新的文档格式。
$ javadoc -html5 AddNum.java
Loading source file AddNum.java...
Constructing Javadoc information...
Building index for all the packages and classes...
Standard Doclet version 21.0.2+13-LTS-58
Building tree for all the packages and classes...
Generating .\AddNum.html...
AddNum.java:32: error: invalid use of @return
* @return Nothing.
^
AddNum.java:16: warning: use of default constructor, which does not provide a comment
public class AddNum {
^
Generating .\package-summary.html...
Generating .\package-tree.html...
Generating .\overview-tree.html...
Building index for all classes...
Generating .\allclasses-index.html...
Generating .\allpackages-index.html...
Generating .\index-all.html...
Generating .\search.html...
Generating .\index.html...
Generating .\help-doc.html...
1 error
1 warning
$
它将会生成如下的文档：
