Java 注释（Java Doc Comment）与注解（Annotation）

Java 注释（Java Doc Comment）与注解（Annotation）

注解（Annotation）：又称为 标注，即 Java 标注，是 JDK5.0 引入的一种注释机制。

• Java 语言中的类、方法、变量、参数和包等都可以被标注，用来对这些元素进行说明，注释。

• 和 Javadoc（文档注释） 不同，Java 标注可以通过反射获取标注内容。

• 也叫元数据。一种代码级别的说明。

• 它不会直接影响到程序的语义，只是作为注解（标识）存在，我们可以通过反射机制编程实现对这些元数据（用来描述数据的数据）的访问。

注释（Note）：用于一些程序进行注释，内容可以是编程思路或者是程序的作用，为了方便自己或他人阅读代码。

• 注释内容是：不会被编译的内容，只是解释说明。

• 使用 idea 的同学，建议去设置 不同的注释为不同的颜色。有奇效哦。

单行注释，以 ‘//’ 为标识，只能注释单行内容。

• 当编译器执行到标识符 ‘//’ 时，会自动忽略该行中标识符之后的的所有文本。

@Test
public void text1() {
    System.out.println("ggggggg");// 输出
    // System.out.println("hjjjjjjh");
    System.out.println("ggggggg");// 输出
}

• 建议：单行注解写在单独一行，即方便阅读又符合阿里巴巴的 Java 开发规范

多行注释，以 ‘/*’ 标识符开头、以 ‘*/’ 标识符结束，注释多行内容 或 内容段。

• 当编译器执行到标识符 ‘/*’ 时，会扫描找到下一个 ‘*/’，并忽略两者之间的任何文本；

• 也就是说，可以在多行注释里添加单行注释。

@Test
public void text2() {
    int i = 1, b = 2;
    double d = 3.0/*, f = 6.0*/;
    System.out.println("i = " + i);
    System.out.println("b = " + b);
    System.out.println("d = " + d);
    //System.out.println("f = " + f);
    /*
    // System.out.println("ggggggg");
    System.out.println("hjjjjjjh");
    System.out.println("ggggggg");
     */
}

• 建议：开头标识符和结尾标识符都写在单独一行，注释之间不要嵌套。

文档注释，以 ‘/**’ 标识符开头、以 ‘*/’ 标识符结束。

• 文档注释 和 多行注释很相似，但功能完全不同。

Javadoc 是 Sun 公司提供的一种工具，它可以从程序源代码中抽取类、方法、成员等注释，然后形成一个和源代码配套的 API 帮助文档。也就是说，只要在编写程序时以一套特定的标签注释，在程序编写完成后，通过 Javadoc 就形成了程序的 API 帮助文档。

• 文档注释只写在 类、类方法、类属性 上，其它地方的 文档注释不会被 Javadoc 处理，等于不写，当然也可以当成 不规范的多行注释。

• 当编译器执行到标识符 ‘/*’ 时，会扫描找到下一个 ‘*/’，并忽略两者之间的任何文本，同时将其中的文本交给 Javadoc 工具来处理。

• 使用 idea 的同学，添加了阿里巴巴插件Alibaba Java Coding Guidelines插件后，可以预览文档注释的结果。

• 默认生成的文档注释，例子：

/**
 * 类的主要描述
 *
 * @author LJM
 * @version 1.0
 * @date 2022/8/3
 */

/**
 * 方法的主要描述
 *
 * @param e 实体类
 * @return 是否成功 1/0
 */

• 文档注释是怎么创建的？键入 '/**' + Enter(回车)。

这是默认的样式：

/**
 * 类
 * @param <E>
 * @param <PK>
 */

/**
 * 方法
 * @param e
 * @return
 */

• 文档注释中有一些 特殊标签，或以 ‘@’ 开头，后面跟一个指定的名字；或以 ‘{@’ 开头，以 ‘}’ 结束。

如：

/**
 * 数据操作业务 基类
 *
 * @param <E>  [描述]
 * @param <PK> [描述]
 *
 * @author [作者]
 * @date [时间值]
 * @version [版本]
 */

常用的文档注释的特殊标签

• 主要描述：一般在 ‘/**’ 的下一行写，是类或方法的主要描述，支持 HTMl 的 p、tt 等标签。

• @author ，用来标识作者，一般用于类注释。如：@author 李氏

• @deprecated ，用来指定一个类或方法已过期，表示不建议使用该类或方法。如：@deprecated [描述]

• @param ，用来说明一个方法的参数或一个类的泛型参数。如：@param [参数] [描述]

• @return ，用来说明返回值类型，一般用于方法注释。如：@return [返回值的解释]

• @version ，用来指定类的版本，一般用于类注释。如：@version [版本号]

• @since ，用来说明从哪个版本开始有这个函数或属性。如：@since [版本号]

• @see ，用来指向另一个类，一般是子类用来指向父类 或 实现指向接口，链接到另一个位置。如：@see [类的全限定名称]

• @exception 和 @throws ，用来说明可能抛出异常的说明。如：@exception [异常] [描述]、@throws [异常] [描述]

• @tag 格式的标签称为：块标签，只能放在 主要描述 后面。

• {@tag} 格式的标签称为内联标签，可以放在文本注释中的任何位置，如 主要描述中、p 标签内、快标签内。

至于如何生成 API 文档、文档注释的标签、Javadoc 命令等，可以参考下面的文章。
Java的三种注释

(二发)如果对你有帮助，点赞可好！！