@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Target(ElementType.METHOD)
@Target 是一个元注解,用于指定被它修饰的注解能被应用到哪些程序元素上。这里的 ElementType.METHOD 指定了该自定义注解只能应用于方法上。ElementType 是一个枚举类型,它有多个值,比如 TYPE(用于类、接口、枚举声明),FIELD(用于字段声明),METHOD(用于方法声明)等,这意味着你可以控制你的注解能够被应用的范围。
@Retention(RetentionPolicy.RUNTIME)
@Retention 元注解用来指示被它所注解的注解保留时间的长短。这里使用的是 RetentionPolicy.RUNTIME,意味着这个自定义注解不仅在编译期被保留,还会在运行时保留,可以被反射机制读取。RetentionPolicy 也有其他两个值:SOURCE(只保留在源码中,编译时会被丢弃)和 CLASS(保留在编译后的class文件中,但运行时JVM会忽略它)。选择 RUNTIME 让注解在程序运行期间仍然有效,使得我们可以在程序执行过程中通过反射来访问这些注解信息。
@Documented
@Documented 注解表明被它所注解的注解应该被包含在生成的JavaDoc文档中。也就是说,如果某个类或者方法使用了带有 @Documented 的自定义注解,那么在生成API文档时,这个注解及其相关信息也会被一并记录下来,这对于对外部开发者说明API的行为和要求非常有用。
综上所述,这三个元注解一起使用,定义了一个只能应用于方法、在运行时可访问、并且会被包含在JavaDoc文档中的自定义注解。这种组合常用于创建具有特定功能或约束的注解,比如标记一个方法需要进行特殊处理(如事务管理、性能监控、权限检查等),并且这些信息对开发者在阅读代码或文档时都是可见和可用的。