如何仅抑制Java 21 Javadoc DocLint的“无主描述”警告？

一、仅抑制主描述缺失警告的配置方法 #

Java 21的DocLint规则相比Java 17更严格，原有的/** @return foo. */格式Getter注释，现在会触发“no main description”警告（对应missing-summary检查项）。要仅抑制该特定警告、保留其他缺失类Javadoc检查，可在Maven Javadoc Plugin中添加细粒度的lint参数：

修改pom.xml中的maven-javadoc-plugin配置，在<additionalparam>里组合开启全量检查并关闭missing-summary项：

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-javadoc-plugin</artifactId>
      <version>3.5.0</version> <!-- 需使用兼容Java 21的插件版本 -->
      <configuration>
        <additionalparam>-Xlint:all -Xlint:-missing-summary</additionalparam>
      </configuration>
    </plugin>
  </plugins>
</build>

这样配置后，仅会关闭主描述缺失的警告，参数、异常等其他Javadoc缺失问题仍会被检测到。

二、向Javadoc团队反馈问题的步骤 #

如果上述细粒度抑制方法无法生效（比如插件版本不支持该参数），可按以下步骤向OpenJDK的Javadoc团队反馈：

• 先验证问题根源：用javadoc命令行直接测试，比如编写包含目标Getter的简单类，执行javadoc -Xlint:all YourClass.java，确认Java 21确实会触发警告、Java 17不会，排除Maven插件的干扰。
• 提交Jira Issue：进入OpenJDK的Jira平台，创建新Issue，项目选择JDK，组件选择javadoc。
• 提供详细信息：
  • 明确标注使用的Java版本（Java 21）
  • 附上最小可复现的代码示例（比如一个带简化Getter注释的类）
  • 说明触发警告的命令行或Maven配置参数
  • 对比Java 17与Java 21的行为差异
  • 阐述该注释格式在Getter场景下的合理性，建议调整规则或提供更精准的抑制选项

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