174. Java 注释 - 声明注释类型

🎯 注释替代代码中的文档信息

在传统的 Java 编程实践中，团队可能会在每个类的开头插入详细的注释，用以提供关于类的元数据（如作者、修改日期、版本等）。这种方式虽然有效，但随着项目变得越来越复杂，可能会导致冗长和重复的注释，尤其是当多个类共享类似的信息时。

例如，以下是一个传统的注释方式：

public class Generation3List extends Generation2List {

   // Author: John Doe
   // Date: 3/17/2002
   // Current revision: 6
   // Last modified: 4/12/2004
   // By: Jane Doe
   // Reviewers: Alice, Bill, Cindy

   // class code goes here

}

📝 定义自定义注释类型

为了使代码更加简洁和结构化，可以使用自定义注释类型来替代这些繁琐的注释信息。定义自定义注释类型需要使用 @interface 关键字，它的语法类似于接口定义，但用于定义注释类型。注释类型的元素就像方法一样，可以定义返回类型和默认值。

下面是一个自定义注释类型的定义示例，用于替代上面的类级注释：

@interface ClassPreamble {
   String author();                  // 作者
   String date();                    // 日期
   int currentRevision() default 1;   // 当前版本，默认值为1
   String lastModified() default "N/A";  // 最后修改日期，默认值为 "N/A"
   String lastModifiedBy() default "N/A";  // 最后修改人，默认值为 "N/A"
   String[] reviewers();             // 审阅者，注意使用数组
}

🎯 注释元素说明

• 元素声明： 自定义注释的元素类似于方法声明。每个元素都有一个返回类型（如 String、int 或数组类型）。有些元素可以提供默认值，如果不提供，使用默认值。
• 数组： 在注释中，可以使用数组类型（如 String[]）来存储多个值。例如，reviewers 数组可以包含多个审阅者。

📝 使用自定义注释

一旦定义了注释类型，就可以在代码中使用它，并为注释的元素提供具体的值。以下是如何在类声明中使用 @ClassPreamble 注释的示例：

@ClassPreamble(
   author = "John Doe",
   date = "3/17/2002",
   currentRevision = 6,
   lastModified = "4/12/2004",
   lastModifiedBy = "Jane Doe",
   reviewers = {"Alice", "Bob", "Cindy"}
)
public class Generation3List extends Generation2List {

   // class code goes here

}

📌 注释文档化

为了确保自定义注释在 Javadoc 生成的文档中能够显示，必须使用 @Documented 注释对注释类型进行标记。这使得 Javadoc 工具能够识别和处理该注释，生成包含相关信息的文档。

import java.lang.annotation.*;

@Documented
@interface ClassPreamble {
   String author(); 
   String date();  
   int currentRevision() default 1;
   String lastModified() default "N/A";
   String lastModifiedBy() default "N/A";
   String[] reviewers();
}

🎯 @Documented 注释的作用

• @Documented： 这是一个元注释（meta-annotation），它会告知 Javadoc 工具在生成文档时包括此注释的相关信息。没有 @Documented，自定义注释不会出现在Javadoc 文档中。

📝 总结

• 自定义注释类型 可以替代传统的类头部注释，使代码更加结构化和可维护。
• 通过 @interface 语法定义注释类型，并可以为注释类型元素指定默认值。
• 在使用自定义注释时，为每个元素提供实际的值，使其能更好地传达元数据。
• 使用 @Documented 注释确保自定义注释会出现在 Javadoc 文档中，提升文档的可读性。