Java 的文档注释常用于描述类、方法、变量等的功能和用法，在实际开发中是非常重要的，以帮助其他开发者更好地理解代码。下面将对 Java 文档注释的基本语法、标签和示例进行详细介绍。

基本语法

Java 文档注释以 /** 开头，以 */ 结尾，形如：

/**
 * 这是一个示例类。
 */
public class ExampleClass {
    // ...
}

在这两个标记之间，可以包含一些特殊的注释标签，用于描述类、方法、字段等元素的信息，下面将详细介绍。

常用标签

Java 文档注释支持多种标签，用于描述不同类型的信息，以下是一些常用的标签。

@param

用于描述方法的参数，形如：

/**
 * 求两个整数之和。
 *
 * @param a 加数
 * @param b 加数
 * @return 两数之和
 */
public int add(int a, int b) {
    return a + b;
}

@return

用于描述方法的返回值，形如：

/**
 * 求两个整数之和。
 *
 * @param a 加数
 * @param b 加数
 * @return 两数之和
 */
public int add(int a, int b) {
    return a + b;
}

@throws

用于描述方法可能抛出的异常，形如：

/**
 * 求两个整数之商。
 *
 * @param a 被除数
 * @param b 除数
 * @return 两数之商
 * @throws IllegalArgumentException 如果除数为0
 */
public int divide(int a, int b) throws IllegalArgumentException {
    if (b == 0) {
        throw new IllegalArgumentException("除数不能为0");
    }
    return a / b;
}

@deprecated

用于表示一个元素已经过时，不建议使用，形如：

/**
 * @deprecated 请使用 {@link #add(int, int)} 方法代替
 */
@Deprecated
public int plus(int a, int b) {
    return a + b;
}

@since

用于表示自哪个版本开始使用此元素，形如：

/**
 * 从字符串中提取数字。
 *
 * @param str 待提取的字符串
 * @return 数字
 * @since 1.1
 */
public int extractNumber(String str) {
    // ...
}

@see

用于表示与此元素相关的其他元素，形如：

/**
 * 求两个整数之和。
 *
 * @param a 加数
 * @param b 加数
 * @return 两数之和
 * @see #subtract(int, int) 相关方法：subtract
 */
public int add(int a, int b) {
    return a + b;
}

@version

用于表示元素的版本号，形如：

/**
 * 这是一个示例类。
 *
 * @version 1.0
 */
public class ExampleClass {
    // ...
}

其他标签

除了上述常用标签之外，还有许多其他标签，例如：

• @link
• @deprecated
• @note
• @example
• @requires
• @ensures
• @signal
• @threadsafety
• @serial
• @serialData
• @serialField
• @indextable
• 等等

示例

下面是一个示例类，其中演示了如何使用常用的 Javadoc 标签：

/**
 * 这是一个示例类。
 *
 * @author John
 * @since 1.0
 * @version 1.0
 */
public class ExampleClass {

    /**
     * 求两个整数之和。
     *
     * @param a 加数
     * @param b 加数
     * @return 两数之和
     * @throws IllegalStateException 如果发生溢出
     */
    public int add(int a, int b) throws IllegalStateException {
        if (a > Integer.MAX_VALUE - b) {
            throw new IllegalStateException("发生了加法溢出");
        }
        return a + b;
    }

    /**
     * 求两个整数之差。
     *
     * @param a 被减数
     * @param b 减数
     * @return 两数之差
     */
    public int subtract(int a, int b) {
        return a - b;
    }

    /**
     * 求两个整数之积。
     *
     * @param a 乘数
     * @param b 乘数
     * @return 两数之积
     */
    public int multiply(int a, int b) {
        return a * b;
    }

    /**
     * 求两个整数之商。
     *
     * @param a 被除数
     * @param b 除数
     * @return 两数之商
     * @throws IllegalArgumentException 如果除数为0
     */
    public int divide(int a, int b) throws IllegalArgumentException {
        if (b == 0) {
            throw new IllegalArgumentException("除数不能为0");
        }
        return a / b;
    }

    /**
     * 求两个整数之模。
     *
     * @param a 被模数
     * @param b 模数
     * @return 两数之模
     * @throws IllegalArgumentException 如果模数为0
     */
    public int mod(int a, int b) throws IllegalArgumentException {
        if (b == 0) {
            throw new IllegalArgumentException("模数不能为0");
        }
        return a % b;
    }

}

结束语

Javadoc 是 Java 中一种非常有用的工具，可以帮助开发者更好地管理和维护代码，在团队协作中也显得尤为重要，建议开发者在编写代码时认真编写 Javadoc 注释。希望本文能够对开发者了解 Java 文档注释有所帮助。

如果您在使用 Javadoc 注释时遇到了问题或存在不理解的地方，欢迎在本文评论区留言，我会尽快回复您的问题。

感谢您的阅读，希望本文对您有所帮助，如果觉得不错，请点赞、评论和分享，您的支持是我最大的动力！

谢谢！