Javadoc Config
[TOC]
该文章主要介绍如何在Gradle中配置javadoc的参数，该文基于Gradle8.3的版本，是用的是kotlin DSL的配置方式，Groovy的配置方式请自行转换，更早或者更晚的版本，如果存在差异，以后有时间再行介绍。
正文
该文的起因是，我在对现有的Maven项目迁移成Gradle项目的过程中，发现在处理javadoc的任务，一直出现html标签检查的问题，导致javadoc的task一直无法正常完成。未能在网上找到准确处理该问题的文章，继而想将此问题的正确解决方案形成文字供需要的人查阅。
在一些情况下，我们需要在注释中提供详细示例表格的时候，可能会用到html的一些标签，以更加直观展示，但在javadoc的规范中是不允许的，这个时候，我们可以将对应的javadoc检查进行关闭，使用-Xdoclint:(-)<group> 开启或关闭特别组别的警告，group 参数可以是下列中的一个：[accessibility, html, missing, reference, syntax]。
通过javadoc.options配置（推荐）
可以通过提供指定javadoc.options的文件，对javadoc的参数进行指定，增删参数可以直接在该配置文件中配置，可以使build.gradle.kts脚本更加简洁。
- <font color="red">build.gradle.kts</font>
tasks.withType<Javadoc> {
options {
memberLevel = JavadocMemberLevel.PACKAGE
// 指定项目根目录(layout.projectDirectory.asFile)下的'javadoc.options'文件，对javadoc的参数进行配置，可以指定多个文件。
optionFiles = listOf(File(layout.projectDirectory.asFile, "javadoc.options"))
}
// javadoc检查错误不中断后续流程
isFailOnError = false
}
optionFiles可以指定多个，对于多模块的项目，可以将公共的配置项放到项目根目录下，差异配置项配置文件放置到各自的模块目录下。但有些参数只能指定一次的，就不能在指定的多个文件中同时出现。否则会出现类似如下的错误提示：
encoding重复配置的时候，会出现类似如下的错误提示：
<font color="red">2023-09-28T11:34:09.668+0800 [ERROR] [system.err] javadoc: 错误 - -encoding选项只能指定一次。</font>
- <font color="red">javadoc.options</font>
-Xdoclint:none
-encoding 'UTF-8'
-verbose
# 生成源代码页面，用于docs的跳转链接
-linksource
javadoc的参数可以使用JDK中的javadoc指令进行查看。
javadoc -help
通过build.gradle.kts脚本配置
直接是用build.gradle.kts脚本进行javadoc的选项进行配置，不推荐使用该方法。
tasks.withType<Javadoc> {
options {
memberLevel = JavadocMemberLevel.PACKAGE
}
// 需要将options实例强制转换为StandardJavadocDocletOptions类型，才有该方法
(options as StandardJavadocDocletOptions).addStringOption("Xdoclint:none","-quiet")
// javadoc检查错误不中断后续流程
isFailOnError = false
}
因为该配置方法需要强制类型转换，因此可能会存在后续版本不兼容的问题，而且如果配置项多的话，会增加build.gradle.kts脚本的复杂度。
附录
javadoc -X的可选项：
-Xdoclint:[<group>](<level>)
# Enable or disable specific checks for problems in javadoc comments, where <group> is one of accessibility, html, missing, reference, or syntax, and <level> is one of ignore, warning, or error.
# @since 8
-Xdoclintformat <fmt>
# Format of output when doclint is run. Formats include msvs, html, text, xml. No format is specified by default. To use a format, specify -Xdoclint and -Xdoclintformat <fmt> in the javadoc command.
# @since 9
-Xdocrootparent <overview>
# Parent of the overview summary for frames-based output. If not specified, the overview summary will be a top-level file. The argument is either the URL for the parent of the overview or the relative path to the directory that contains the overview file.
# @since 9
-Xmaxerrs <num>
# Set the maximum number of errors to print.
# @since 9
-Xmaxwarns <num>
# Set the maximum number of warnings to print.
# @since 9
-Xold
# Do not use the new language features introduced in JDK 5 (generics, enums, varargs, for-each loop, and static import), and enforce third-party tag usage.
# @since 5
-Xprofile
# Enables proprietary API features.
# @since 1.2