如何在Gradle 8.2构建中抑制Java 21的Javadoc警告？

问题复盘 #

升级到Java 21和Gradle 8.2后，尝试通过addStringOption添加Xdoclint参数抑制Javadoc警告，但配置未生效，警告依旧出现，且生成的javadoc.options文件中看不到指定的参数。

有效解决方案 #

方案1：使用Gradle封装的xdoclint属性（推荐，Gradle 7.1+支持） #

Gradle从7.1版本开始为Javadoc任务提供了原生的xdoclint配置属性，无需手动拼接字符串选项，兼容性更好：

// 仅抑制缺失Javadoc注释的警告
tasks.withType(Javadoc) {
    options.xdoclint = '-missing'
}

// 或者禁用所有Javadoc检查
tasks.withType(Javadoc) {
    options.xdoclint = 'none'
}

方案2：修正字符串选项的传递方式 #

如果方案1不生效，可调整addStringOption的参数，将第二个参数从null改为空字符串（部分JDK版本需要占位符来识别选项）：

// 抑制缺失注释警告
tasks.withType(Javadoc) {
    options.addStringOption('Xdoclint:-missing', '')
}

// 禁用所有Javadoc警告
tasks.withType(Javadoc) {
    options.addStringOption('Xdoclint:none', '')
}

多模块项目适配 #

如果是多模块项目，需要在根项目的构建脚本中通过subprojects块将配置应用到所有子项目：

subprojects {
    tasks.withType(Javadoc) {
        options.xdoclint = '-missing'
    }
}

验证配置是否生效 #

执行以下命令查看Javadoc任务的详细日志：

./gradlew clean javadoc --info

检查生成的build/tmp/javadoc/javadoc.options文件，确认其中包含-Xdoclint:-missing或-Xdoclint:none参数，说明配置已正确生效。

针对Gradle 8.2和Java 21的注意事项 #

1. Gradle 8.2对Javadoc任务的配置逻辑做了优化，优先使用官方封装的属性（如xdoclint）而非手动添加JVM参数，避免配置不兼容问题。
2. Java 21的Javadoc工具对Xdoclint的规则未做大幅变更，问题核心在于Gradle的配置传递方式，而非JDK版本。

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