Java 文档注释学习笔记

本文主要介绍Java中的文档注释，包括注释的格式、注释标记的含义和如何使用。

注释的格式

Java中的文档注释以/**开头，以*/结尾，例如：

Copy Code
/**
 * 这是一段文档注释。
 */

注释内容应该放在/**和*/之间，并且每行以*开头，例如：

Copy Code
/**
 * 这是一段
 * 多行的
 * 文档注释。
 */

如果注释只有一行，则可以省略*，例如：

Copy Code
/** 这是一段单行的文档注释。 */

注释标记的含义

Java中的文档注释可以包含多个注释标记（Tag），用于指示注释的含义，常见的注释标记包括：

• @param：描述方法的参数。
• @return：描述方法的返回值。
• @throws：描述方法可能抛出的异常。
• @see：引用其他类、方法或者字段。
• @deprecated：标记方法已经废弃。

下面是一个例子，展示了如何使用这些注释标记：

Copy Code
/**
 * 这个方法用于计算两个整数的和。
 *
 * @param a 第一个整数。
 * @param b 第二个整数。
 * @return 两个整数的和。
 * @throws IllegalArgumentException 如果传入的参数小于0。
 * @see #subtract(int, int)
 * @deprecated 请使用addExact替代。
 */
public static int add(int a, int b) throws IllegalArgumentException {
    if (a < 0 || b < 0) {
        throw new IllegalArgumentException("参数不能小于0");
    }
    return a + b;
}

实例

下面是一个实例，展示了如何使用文档注释来描述一个类和其中的方法和字段：

Copy Code
/**
 * 这个类用于演示文档注释的使用。
 */
public class DocumentedClass {
    private int field;

    /**
     * 这个方法用于设置字段的值。
     *
     * @param value 字段的新值。
     */
    public void setField(int value) {
        this.field = value;
    }

    /**
     * 这个方法用于获取字段的值。
     *
     * @return 字段的值。
     */
    public int getField() {
        return this.field;
    }

    /**
     * 这个方法用于计算两个整数的积。
     *
     * @param a 第一个整数。
     * @param b 第二个整数。
     * @return 两个整数的积。
     * @throws IllegalArgumentException 如果传入的参数小于0。
     * @see #setField(int)
     * @deprecated 请使用multiplyExact替代。
     */
    public static int multiply(int a, int b) throws IllegalArgumentException {
        if (a < 0 || b < 0) {
            throw new IllegalArgumentException("参数不能小于0");
        }
        return a * b;
    }
}

以上就是Java文档注释的学习笔记和实例，希望对你有所帮助。