---
title: "13-javadoc注释"
created: 2025-12-02
tags:
  - 项目
aliases:
  - javadoc注释
---
# javadoc注释

`Javadoc` 注释是 Java 编程语言中用于生成 API 文档的一种注释格式。它通过特殊的注释语法来为 Java
类、方法、构造函数、字段等提供文档说明，通常用于生成自动化的文档。

### Javadoc 注释的基本格式：

Javadoc 注释以 `/**` 开始，以 `*/` 结束。在注释块中，可以使用一些预定义的标签来描述类、方法或字段的功能及其参数、返回值等信息。

```java
/**

 * 这是一个简单的示例类

 * 这里可以对类进行描述，介绍它的功能和用途。

 */

public class MyClass {

    /**

     * 这是一个计算两个数和的方法

     *

     * @param a 第一个数字

     * @param b 第二个数字

     * @return 返回两个数字的和

     */

    public int add(int a, int b) {

        return a + b;

    }

}
```

### 常用的 Javadoc 标签：

- `@param`：用于描述方法的参数。
- `@return`：用于描述方法的返回值。
- `@throws` 或 `@exception`：用于描述方法可能抛出的异常。
- `@see`：用于引用相关的类或方法。
- `@deprecated`：标记某个方法或类已废弃，通常会附带替代方法。
- `@since`：表示该方法或类在特定的版本中开始引入。
- `@author`：指示类的作者。
- `@version`：指示类的版本。

### 生成 Javadoc 文档：

在编写好 Javadoc 注释后，可以使用 JDK 自带的 `javadoc` 工具来生成 API 文档。命令如下：

```text
javadoc -d <输出目录> <源文件路径>
```

例如：

```text
javadoc -d doc MyClass.java
```

执行该命令后，会在指定的目录中生成一个 HTML 格式的文档，这个文档可以用来查看 API 的详细信息。

### 示例：

```java
/**

 * 计算器类，提供基本的数学运算。

 * @author John Doe

 * @version 1.0

 * @since 2024-11-12

 */

public class Calculator {

    /**

     * 计算两个整数的和。

     * @param num1 第一个数字

     * @param num2 第二个数字

     * @return 两个数字的和

     */

    public int add(int num1, int num2) {

        return num1 + num2;

    }

    /**

     * 计算两个整数的差。

     * @param num1 第一个数字

     * @param num2 第二个数字

     * @return 两个数字的差

     */

    public int subtract(int num1, int num2) {

        return num1 - num2;

    }

}
```

### 结果：

生成的 Javadoc 会包含以下信息：

- 类 `Calculator` 的描述和作者、版本等信息。
- 每个方法的功能、参数及返回值。
- 文档化 API，方便开发人员快速理解类的功能。

### 总结：

`Javadoc` 注释不仅帮助开发人员理解代码的功能，还能自动生成 API 文档，便于团队协作和项目维护。通过规范的注释，可以提高代码的可读性和可维护性。

---

**项目分区导航**：⬅️ [[12-@Slf4j|12-@Slf4j]] | 13-javadoc注释 | ➡️ [[14-业务逻辑|14-业务逻辑]]