Java 文档注释精通：Javadoc 工具与注释类型全解析

Java 语言支持三类注释：

本章详解 Javadoc，展示如何利用 Javadoc 为 Java 代码生成有用文档。

什么是 Javadoc？

Javadoc 是随 JDK 提供的工具，用于从 Java 源代码按预定义格式生成 HTML 格式的 Java 代码文档。

下面简单示例中 /*….*/ 内为 Java 多行注释，// 前一行为单行注释：

示例

/**
 * HelloWorld 程序实现仅在标准输出显示 "Hello World!" 的应用。
 *
 * @author Zara Ali
 * @version 1.0
 * @since 2014-03-31
 */
public class HelloWorld {
    public static void main(String[] args) {
        // 在标准输出打印 Hello, World!
        System.out.println("Hello World!");
    }
}

描述部分可包含所需 HTML 标签。例如下例使用 <h1>....</h1> 作为标题，<p> 用于段落换行：

示例

/**
 * <h1>Hello, World!</h1>
 * HelloWorld 程序实现仅在标准输出显示 "Hello World!" 的应用。
 * <p>
 * 程序中添加适当注释使其更友好，被视为高质量代码。
 *
 * @author Zara Ali
 * @version 1.0
 * @since 2014-03-31
 */
public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello World!");
    }
}

Javadoc 标签

javadoc 工具识别以下标签：

示例

下面程序使用文档注释的几个重要标签。可根据需求使用其他标签。

AddNum 类文档将生成 HTML 文件 AddNum.html，同时也会创建名为 index.html 的主文件。

import java.io.*;
/**
 * <h1>Add Two Numbers!</h1>
 * AddNum 程序实现仅将两个给定整数相加并打印输出的应用。
 * <p>
 * <b>Note:</b> 程序中添加适当注释使其更友好，被视为高质量代码。
 *
 * @author Zara Ali
 * @version 1.0
 * @since 2014-03-31
 */
public class AddNum {
    /**
     * 此方法用于添加两个整数。这是
     * 类方法最简单形式，仅为展示各种 javadoc 标签用法。
     * @param numA 这是 addNum 方法的第一个参数
     * @param numB 这是 addNum 方法的第二个参数
     * @return int 返回 numA 和 numB 之和。
     */
    public int addNum(int numA, int numB) {
        return numA + numB;
    }
    /**
     * 这是使用 addNum 方法的主方法。
     * @param args 未使用。
     * @return 无。
     * @exception IOException 输入错误时。
     * @see IOException
     */
    public static void main(String args[]) throws IOException {
        AddNum obj = new AddNum();
        int sum = obj.addNum(10, 20);
        System.out.println("10 和 20 的和为 :" + 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
$

可在此查看所有生成文档 —— AddNum。若使用 JDK 1.7，javadoc 生成的 stylesheet.css 不太理想，建议从 https://docs.oracle.com/javase/7/docs/api/stylesheet.css 下载使用标准样式表。