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