@documented使注解出现在javadoc中，提升api可读性；@inherited使类级注解被子类继承，仅适用于type且不作用于方法、字段等。二者职责分离，可组合使用但互不影响。
@Documented 和 @Inherited 是 Java 中两个功能明确、互不干扰的元注解，它们分别控制注解是否出现在 Javadoc 文档中、以及类级注解能否被子类自动继承。用错或忽略它们，容易导致文档缺失或继承行为不符合预期。
@Documented：让注解“写进文档里”
加上 @Documented 后，Javadoc 工具在生成 API 文档时，会把被标注的注解本身也一并展示出来。这对团队协作和接口可读性很关键——别人看文档就能立刻知道某个类或方法被打了什么语义标签。
- 它只影响文档生成，不改变运行逻辑，也不影响反射获取
- 适合用于有业务含义的注解，比如 @ApiVersion("v2")、@Experimental、@DeprecatedSince("2026.1")
- 如果自定义注解没加 @Documented，即使用了，Javadoc 默认不会显示该注解名称和参数值
- 示例：@Documented @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME)
public @interface Loggable { String value() default ""; }
@Inherited：让类级注解“传给子类”
@Inherited 只对标注在 类 上的注解生效，且仅作用于类的继承关系（即子类 extends 父类），不适用于接口实现、方法、字段或参数。
- 它不改变注解本身的定义，只是开启“继承传播”开关
- 典型场景是统一基类策略，比如父类加了 @Secured，所有子类自动具备安全校验能力
- 注意：方法上的注解（如 @Override）不会被继承；@Inherited 对 METHOD、FIELD 等 ElementType 无效
- 示例：@Inherited @Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME)
public @interface SecuredBase { }
组合使用时的关键细节
两者可以同时出现，但职责完全分离：一个管“人看不看得见”，一个管“子类有没有”。实际开发中常见组合如下：
- 面向公共 API 的注解，建议同时加 @Documented + @Retention(RUNTIME)，便于文档查阅和运行时处理
- 需要子类自动继承的策略型注解，必须加 @Inherited，并确保只用于 TYPE（类/接口/枚举）
- @Inherited 不会跨模块或跨 jar 生效——子类和父类需在同一个类加载器上下文才可靠
- 不要误以为加了 @Inherited 就能“继承方法上的注解”，这是常见误解
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
