Java函数文档注释编写规范及示例

Java函数文档注释是一种规范化的注释格式，用于描述函数的功能、参数、返回值和异常等信息。良好的函数文档注释可以方便其他开发人员理解和使用函数，并且可以通过工具生成相应的文档。

下面是Java函数文档注释的编写规范及示例：

1. 函数文档注释的格式为连续的多行注释，以/** 开始，以*/ 结束。可以使用多个星号*来对注释进行格式化，使其更易读。

2. 函数文档注释应该在函数声明之前进行编写，以便其他开发人员可以立即看到函数的文档。

3. 函数文档注释应该包括以下内容：

- 函数的功能描述：对函数的功能进行简要描述，使其他人能够理解其作用。

- 参数说明：对每个参数进行说明，包括参数类型、名称和含义。

- 返回值说明：对函数的返回值进行说明，包括返回值的类型和含义。

- 异常说明：如果函数可能会抛出异常，应该对异常进行说明，包括异常的类型和触发条件。

4. 函数文档注释的示例：

/**
 * 计算两个整数的和
 * 
 * @param a       个整数
 * @param b 第二个整数
 * @return 两个整数的和
 * @throws IllegalArgumentException 如果参数为负数，则抛出该异常
 */
public int add(int a, int b) {
    if (a < 0 || b < 0) {
        throw new IllegalArgumentException("参数不能为负数");
    }
    return a + b;
}

在上面的示例中，函数的功能是计算两个整数的和。注释通过@param标签对函数的参数进行说明，使用@return标签对函数的返回值进行说明，使用@throws标签对可能抛出的异常进行说明。

通过遵循上述的规范，可以为函数添加清晰和易读的文档注释，提高代码的可维护性和可读性。此外，还可以使用一些工具自动生成函数的文档，如JavaDoc等，更加方便地查看和生成函数文档。