Java基础之注释
在上篇的代码示例中可以看到我加入了很多的中文说明，汉字的前面都加了两个斜杠"//"，这就是注释。
我为了对下一行的代码的作用进行说明，但是我写的文字说明又不想让Java以为是代码，所以就约定一个标记，只要是 // 后面的文字都是不需要编译和运行的。
所以Java注释是一种在代码中添加说明和解释的方式，可以帮助其他开发人员更友好地理解代码的功能和用途。
上面说的//这种叫单行注释，Java注释有三种:
1.单行注释
单行注释是最常见的注释类型，它以两个斜杠（//）开头，仅影响它后面的那行代码。例如：
// 这是一个单行注释，规范是在代码上面一行加
int a = 5; // 定义一个整型变量 a，并赋值为 5, 规范来讲一般不在代码后面加注释
单行注释一般出现在Java代码体中，方法内部中使用。
2.多行注释
多行注释可以跨越多行，它以一个斜杠和一个星号（/）开头，以一个星号和一个斜杠（/）结尾。例如：
/*
* 这是一个多行注释
* 可以跨越多行
*/
int b = 10; /* 定义一个整型变量 b，并赋值为 10 */
这种一般是单行放不下，一段说明的时候使用，和单行的差不多。
3.文档注释
文档注释是一种特殊的多行注释，它以一个斜杠和两个星号（/**）开头，以一个星号和一个斜杠（*/）结尾。文档注释可以用于生成 API 文档，例如使用 Javadoc 工具。例如：
/**
* 这是一个类注释
* @author xh
* @version 1.0
*/
public class Hello{
/**
* 这是一个文档注释，用来说明add方法
* @param num1 第一个整数参数
* @param num2 第二个整数参数
* @return 两个整数的和
*/
public int add(int num1, int num2) {
return num1 + num2;
}
}
文档注释通常用于生成API文档。
因为我们经常新建类，我们以后会常使用文档注释来对类和方法进行说明，比如上面这个就是Hello类的注释，@后面跟着的是标签，表示作者是xh，版本1.0，也可以添加其他标签。
add方法上是一个方法级的文档注释，@param后面表示的是方法的入参，@return后面表示的是方法的结果。
注意在Java中是不能嵌套的，注释不能嵌套注释，就是说不能在一个注释内部再写另一个注释:
// 错误的嵌套注释
int c = 15; /* 这是一个多行注释 // 错误的单行注释 */
注释标签
@符号用于标记特殊标签，这些标签提供了额外的信息来描述方法、字段或类。这些标签可以被Javadoc工具解析，并用于生成格式化的API文档。
是不是很熟悉，安装jdk的时候我们看到过javadoc这个命令，是在jdk安装目录的bin目录下，和javac、java命令同级。
常用的Javadoc标签：
@param <parameter-name> 描述方法的参数。
@return 描述方法的返回值。
@throws <exception-name> 或 @exception <exception-name> 描述方法可能抛出的异常。
@see <reference> 提供对其他类或方法的链接。
@deprecated 标记一个元素为已过时，并可能提供额外的说明。
@since 指出该API是从哪个版本开始引入的。
@version 指出代码的版本信息。
运行一下代码:
/**
* 这是一个数学工具类，提供基本的算术运算功能。
*
* @author xh
* @version 1.0
* @since 2024-05-029
*/
public class MathUtil {
/**
* 计算两个整数的和。
*
* @param a 第一个加数
* @param b 第二个加数
* @return 两个加数的和
*/
public int add(int a, int b) {
return a + b;
}
/**
* 主方法，用于演示MathUtils类的功能。
*
* @param args 命令行参数数组
*/
public static void main(String[] args) {
MathUtil mathUtil = new MathUtil();
int sum = mathUtil.add(5, 3);
System.out.println("5 + 3 = " + sum);
}
}
Javadoc命令使用
下面我们使用javadoc命令来对我们上面编写编写的代码生成对应的接口文档。
还是cmd进入大黑屏，然后输入命令:
javadoc -encoding UTF-8 -d doc -author -version MathUtil.java
可以看到生成了一个doc文件夹，这里就是生成的文档页面，我们进去找到index.html，用浏览器打开，就可以看到这个类的文档信息！
Jdk内置的类，都是用这个生成的，在官网可以看到，但是是英文，看的意义不大。
END
