如何避免Java record中的Javadoc重复编写问题？

核心问题回顾 #

Java Record的设计初衷是减少样板代码，快速创建不可变类，但给Record组件添加@param注释后，若为了参数验证添加紧凑构造函数，启用-Xdoclint:all编译选项会触发构造函数参数未文档化的警告；直接复制组件的@param注释又会造成Javadoc内容重复，需要一种类似@Override方法用{@inheritDoc}的方式复用参数文档。

可行解决方案 #

• 直接在紧凑构造函数上使用{@inheritDoc}
  JDK 11及以上的Javadoc工具支持在Record的紧凑构造函数上添加{@inheritDoc}，它会自动继承Record组件的@param文档，既满足-Xdoclint:all的检查要求，又不会产生重复内容。示例代码：

  /**
   * 不可变的FooBar记录类
   * @param foo 用于XX的字符串组件，不能为空
   * @param bar 用于XX的字符串组件，不能为空
   */
  public record FooBar(String foo, String bar) {
      /**
       * {@inheritDoc}
       */
      public FooBar {
          // 参数验证逻辑
          if (foo == null || foo.isBlank()) {
              throw new IllegalArgumentException("foo不能为空白");
          }
          if (bar == null || bar.isBlank()) {
              throw new IllegalArgumentException("bar不能为空白");
          }
      }
  }
  

• 在构造函数的@param中单独引用组件文档
  若遇到旧版本Javadoc工具不支持构造函数整体{@inheritDoc}的情况，可以在构造函数的每个@param后使用{@inheritDoc}，明确复用对应组件的文档：

  /**
   * 带参数校验的FooBar构造函数
   * @param foo {@inheritDoc}
   * @param bar {@inheritDoc}
   */
  public FooBar {
      // 参数验证逻辑
  }
  

  这种写法虽然需要列出每个@param，但实际内容是复用组件的文档，不会产生重复冗余。

• 临时禁用缺失参数文档的doclint警告（不推荐）
  如果上述方案都无法适配，可在编译时添加参数-Xdoclint:all,-missing来跳过缺失文档的检查，但这会关闭所有缺失Javadoc的警告，可能遗漏其他必要的文档说明，仅建议作为临时应急方案。

内容的提问来源于stack exchange，提问作者Garret Wilson