[Gradle/Maven] 如何禁用JavaDoc Lint

[Gradle/Maven] 如何禁用JavaDoc Lint

Xy718 251 2022-07-08

在规模稍大以上的公司的开发流程中,一般会使用包管理工具:Maven或者Gradle来制作一些公共制品:

  • 静态工具
  • RPC接口定义
  • springboot starter

等等

那么我们对这些静态制品都会有一个要求,就是JavaDoc:
image-1657268281163

静态制品的类定义,属性,函数等等都是需要文档的,这也是默认约定俗成的规范

那么在maven-publish插件推送时,我们经常会遇到某些定义的Tag无法被javaDoc lint通过的问题:
image-1657268824953

image-1657268479547

image-1657268764010
@date标签,在javaDoc中就是不是预定义的标签,所以会被javaDoc lint驳回
但是其实他对后续的文档阅读和使用是没有任何影响的,我只需要在构建过程中配置即可:

Maven

使用 maven-javadoc-plugin,从 3.0.0 版本开始,添加了新的 doclint 配置。

<plugins>
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>3.1.1</version>
        <configuration>
            <doclint>none</doclint> <!-- Turn off all checks -->
        </configuration>
        <executions>
            <execution>
                <id>attach-javadocs</id>
                <goals>
                    <goal>jar</goal>
                </goals>
            </execution>
        </executions>
    </plugin>
</plugins>

但一般来说,不建议使用 none 选项,因为它会跳过所有类型的检查。应该使用 <doclint>all,-missing</doclint> 代替。

在使用早期版本(v3.0.0 之前)时,需要使用不同的设置

<plugins>
  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <configuration>
      <additionalparam>-Xdoclint:none</additionalparam>
    </configuration>
  </plugin>
</plugins>

Gradle

Gradle上的禁用非常简单

if (JavaVersion.current().isJava8Compatible()) {
    allprojects {
        tasks.withType(Javadoc) {
            options.addStringOption('Xdoclint:none', '-quiet')
        }
    }
}

或者

tasks.withType(Javadoc) {
    options.addStringOption('Xdoclint:none', '-quiet')
}

即可


冶心·练体·得技