Java @Documented 注释

Java @Documented 注释是一种特殊的注释，它可以用于 Java 中的注释中，来指定该注释应该被 Java 文档生成工具所记录和保存。简单来说，Java 中的 @Documented 注释可以让我们的注释可以被 Java 文档工具所处理和生成。

语法

Java @Documented 注释的语法非常简单，只需要在注释前面添加 @Documented 标签即可。例如：

/**
 * @Documented Example
 */
public class Demo {
    // class implementation
}

使用场景

一般情况下，我们在编写代码时会添加注释，在编译后会生成 class 文件，但是这些注释只是我们自己看的，如果想让其他人看到这些注释，只能提供给他们源代码。

Java 提供了一个工具 javadoc，用于生成代码文档。在使用 javadoc 进行文档生成时，可以指定 @Documented 注释，生成文档时，就会包括这些注释。

下面是示例代码：

/**
 * 美国队长
 *
 * @author
 * @version 0.1
 * @since 2021/6/8
 */
@Documented
public @interface CaptainAmerica {
    String name() default "Steve Rogers";
    String alias() default "Captain America";
    String[] friends() default {"Bucky Barnes", "Falcon", "Black Widow"};
    String[] enemies() default {};
}

以上代码是一个用来描述美国队长的注解，并使用 @Documented 标签进行标记。当我们使用 javadoc 工具生成文档时，会将这个注解也一并纳入到文档中。

注意事项

• @Documented 注释只能用于注解定义中。
• @Documented 注释不会影响源代码的执行方式，它只是提供了额外的文档信息。
• 使用 @Documented 注释的注解，只有在 javadoc 命令参数下加上 -documented 才会输出。

结论

Java 中的 @Documented 注释能让我们的代码注释被文档生成工具所记录和保存，方便其他人了解和使用我们的代码。虽然使用 @Documented 注释的场景不是很多，但是了解这个注解也是我们扩展 Java 技能的一个方向。