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内置的类都是用这个生成的，在官网可以看到，但是是英文，我看不懂，翻译过来看的意义不大。
原创文章，作者：guozi，如若转载，请注明出处：https://www.sudun.com/ask/78892.html
