什么是 Java 文档注释?
在 Java 中,文档注释是一种特殊的注释形式,它以/**开头,以*/结尾,用于为代码生成 API 文档,方便其他开发者理解代码的功能、参数、返回值等重要信息。通常会被一些文档生成工具(如 Javadoc 工具)读取并处理,进而生成格式规范、易于查看的 HTML 格式的文档。
-
常用标签介绍:
-
@author:
用于指定代码的作者名字,像上述示例中可以表明这个类或者相关代码是谁编写的。例如:@author 张张张,表示作者是 张张张。 -
@version:
用来记录代码的版本号,方便追踪代码在不同阶段的变化情况,比如:@version 2.3,说明当前版本是 2.3 版本。 -
@param:
当方法有参数时,使用这个标签来描述参数的含义、类型以及用途等信息。如上述myMethod方法中的@param num,就是对参数num进行说明,让使用者知道这个参数是干什么的。 -
@return:
针对有返回值的方法,用它来说明返回值的情况,像返回的数据类型、代表的含义等。例如myMethod方法里的@return注释,告知调用者该方法会返回一个经过计算后的整数结果。 -
@throws(或@exception):
如果方法可能抛出某些异常,就可以用这个标签来列举出可能抛出的异常类型以及异常产生的原因等情况,