Java 文档注释

Java - 文档注释（Javadoc）

编写清晰的文档对于代码的可维护性和可理解性至关重要。Java 提供了一种标准方式，使用特殊注释直接在源代码中嵌入文档，这些注释随后可以通过 javadoc 工具处理，生成专业的 API 文档（通常采用 HTML 格式）。

Java 中的注释类型：

类型	语法	描述
单行注释	// text	编译器会忽略从 // 到行尾的所有内容。用于简短解释或临时禁用代码。
多行注释	/* text */	编译器会忽略从 /* 到 */ 之间的所有内容。用于跨多行的较长注释。
文档注释	/** documentation */	javadoc 工具识别的特殊注释格式。必须紧邻类、接口、方法、构造方法或字段声明之前。

什么是 Javadoc？

Javadoc 是 Java 开发工具包（JDK）中包含的一个命令行工具。它解析 Java 源代码文件中的文档注释（/** ... */），并生成 API 文档。

文档注释的结构：

一个 Javadoc 注释包含：

1. 主要描述（Main Description）： 第一句话应是对所描述元素的简洁摘要（类、方法等）。这句话在第一个句号后跟空格或制表符，或者在第一个块标签（block tag）处结束。它用于摘要表格。
2. 详细描述（Detailed Description）： 提供更多细节的附加段落。你可以在描述中使用 HTML 标签（如 <p>、<ul>、<li>、<code>、**、<i>）进行格式化。
3. 块标签（Block Tags）： 以 @ 开头的特殊标签（例如 @param、@return、@throws、@see、@since、@author、@version、{@code}、{@link}），提供关于被文档化元素的特定元数据。

文档注释示例：

/**
 * 表示一个能够进行基本算术运算的简单计算器。
 * <p>
 * 此类提供了加法、减法等方法。
 * 它演示了 Javadoc 注释的使用。
 * </p>
 *
 * @author  你的名字
 * @version 1.1
 * @since   1.0
 */
public class SimpleCalculator {

    /**
     * 将两个整数相加。
     * <p>
     * 这是主要的加法方法。确保输入是有效的整数。
     * 对于浮点数加法，请使用 {@code add(double, double)}。
     * </p>
     *
     * @param numA 第一个整数操作数。
     * @param numB 第二个整数操作数。
     * @return int numA 和 numB 的和。
     * @see #subtract(int, int)
     * @see <a href="https://www.example.com/math_principles">数学原理</a>
     */
    public int add(int numA, int numB) {
        return numA + numB;
    }

    /**
     * 从第一个整数中减去第二个整数。
     *
     * @param numA 被减数。
     * @param numB 减数。
     * @return 减法的结果。
     * @throws IllegalArgumentException 如果 numB 大于 numA（示例条件）。
     */
    public int subtract(int numA, int numB) {
        if (numB > numA) {
             // 异常文档化的示例
             throw new IllegalArgumentException("对于此操作，numB 不能大于 numA");
        }
        return numA - numB;
    }

    // 其他方法将在此之后...
}

常用的 Javadoc 标签：

以下是一些最常用的块标签：

标签	描述
@param parameter-name description	描述方法或构造方法的参数。必须在其后跟着参数名，然后是描述。
@return description	描述方法返回的值（对于 void 方法省略此标签）。
@throws exception-class description 或 @exception exception-class description	记录方法可能抛出的异常。包含异常的完全限定类名。
@see reference	添加一个“另请参阅”条目。可以引用其他类/方法（package.Class#member），链接到外部 URL（<a href=... >...</a>），或提供纯文本。
@since version-text	表示引入此功能时的软件版本（例如，@since 1.2）。
@author author-name	指定类或接口的作者。
@version version-text	指定类或接口的版本（通常与 SCM 版本相关）。运行 javadoc 时需要 -version 选项。
@deprecated description	将元素标记为已弃用，不建议使用。解释原因并提供替代方案。
{@code text}	以代码字体渲染 text，不解释 HTML。适用于描述中的代码片段或标识符。
{@link package.Class#member label}	插入到另一个 Javadoc 元素的内联链接，使用 label 显示（如果省略 label 则显示元素名称）。以代码字体渲染。
{@linkplain ...}	与 {@link} 相同，但标签以普通字体渲染。
{@value package.Class#field}	直接在文档中显示静态 final 字段（常量）的值。

生成 Javadoc 文档：

你可以从终端或命令提示符中使用 javadoc 命令生成文档。

基本用法：

# 为特定的 Java 文件生成文档
javadoc MyClass1.java MyClass2.java

# 为目录（及子目录）中的所有 Java 文件生成文档
javadoc -d output_directory -sourcepath src_directory -subpackages com.mypackage

# 常用选项：
# -d <目录> : 指定生成 HTML 文件的输出目录。
# -sourcepath <路径列表> : 指定查找源文件的位置。
# -classpath <路径列表> : 指定查找引用的类文件的位置。
# -subpackages <包名>[:<包名>...] : 递归处理子包。
# -author : 包含 @author 标签（默认为排除）。
# -version : 包含 @version 标签（默认为排除）。
# -private : 包含 private 成员（默认为 protected/public）。

命令示例：

假设 SimpleCalculator.java 位于 src 目录下 com/example/util 中：

javadoc -d docs -sourcepath src -subpackages com.example.util -author -version

此命令会在 docs 子目录中生成 HTML 文档，处理在 src 目录中找到的 com.example.util 及其子包，并包含作者和版本信息。

最佳实践：

• 文档化所有 public 类、接口、方法和常量。
• 编写清晰简洁的摘要句。
• 必要时提供详细解释，如果有所帮助，包含使用示例（{@code ...} 非常适合此用途）。
• 文档化所有参数（@param）、返回值（@return）和异常（@throws）。
• 使用 @see、{@link} 和 {@linkplain} 来交叉引用相关元素。
• 保持文档与代码更改同步更新。
• 谨慎且正确地使用 HTML 标签进行格式化。
• 配置你的 IDE 以帮助生成 Javadoc 存根。

查阅官方 Oracle Javadoc 文档，获取标签和选项的完整列表。