Java文档注释用法+JavaDoc的使用说明

Java文档注释是一种特殊的注释格式，用于为Java源代码中的类、接口、方法、字段等元素提供说明文档。JavaDoc是Java自带的文档生成工具，可以通过Java代码中的文档注释来生成API文档。

Java文档注释用法

Java文档注释的格式与普通的注释格式略有不同，其中包含了一些特殊的文本标记。一条Java文档注释要以"/*"开头，中间包含注释文本以及标记，以"/"结尾。

JavaDoc支持的标记有很多，这里列举一些常用的：

1. @param：用于描述方法的参数，后面跟上参数名和参数说明。

2. @return：用于描述方法的返回值类型和说明。

3. @throws：用于描述方法可能抛出的异常，后面跟上异常类型和异常说明。

4. @see：用于引用其他类、方法、字段等的文档说明。

5. @version：用于描述版本号。

6. @author：用于描述作者。

下面是一个例子，演示了Java文档注释的用法：

/**
 * 这是一个用于求两个数之和的类。
 * @param a 第一个加数
 * @param b 第二个加数
 * @return 返回两个数之和
 */
public class Adder {
    public int add(int a, int b) {
        return a + b;
    }
}

在这个例子中，我们使用了 @param 标记描述了 add 方法的两个参数，同时使用了 @return 标记描述了 add 方法的返回值。

使用JavaDoc生成API文档

在了解了Java文档注释的用法后，我们可以使用JavaDoc来生成API文档。JavaDoc是Java自带的文档生成工具，通过执行以下命令来使用：

javadoc -d output_dir source_file

其中，-d 表示指定文档输出目录，source_file 是需要生成文档的源代码文件。在生成文档之前，需要在指定的输出目录下创建一个名为"doc-files"的子目录，并在其中存放文档用到的图片、样式文件等资源。

下面是一个例子，演示了如何使用JavaDoc生成API文档：

/**
 * 这是一个用于求两个数之和的类。
 * @param a 第一个加数
 * @param b 第二个加数
 * @return 返回两个数之和
 */
public class Adder {
    public int add(int a, int b) {
        return a + b;
    }
}

在生成文档之前，需要在同一目录下创建一个"doc-files"子目录，并在其中放置一张名为"logo.png"的图片。

执行以下命令生成文档：

javadoc -d docs Adder.java

执行完成后，生成的文档将会保存在"docs"目录下。打开index.html文件，即可看到生成的API文档，其中包含了Adder类的文档说明、方法说明以及参数、返回值等详细信息。

示例说明

下面再举一个例子，演示Java文档注释的用法。

/**
 * 这是一个用于计算圆的面积和周长的类。
 */
public class Circle {
    /**
     * 半径
     */
    private double r;

    /**
     * 构造函数，用于初始化圆的半径。
     * @param r 圆的半径
     */
    public Circle(double r) {
        this.r = r;
    }

    /**
     * 计算圆的面积。
     * @return 返回圆的面积
     */
    public double area() {
        return Math.PI * r * r;
    }

    /**
     * 计算圆的周长。
     * @return 返回圆的周长
     */
    public double perimeter() {
        return 2 * Math.PI * r;
    }
}

在这个例子中，我们使用了Java文档注释描述了Circle类的作用，以及每个方法的参数、返回值等信息。在使用JavaDoc生成API文档后，可以清晰地看到每个方法的详细说明，让使用者更好地了解API的用法。