关闭JDK8中的doclint

By | 3月 1, 2017
0 Comment

原文：http://blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html

Javadoc doclint

Java中使用Javadoc工具来生成文档，它将源代码中的注释抽取出来，生成一个格式工整的API文档（HTML格式）。

在JDK 8之前，开发者可以在注释中写任何模糊的HTML片段，@link也可以指向一个不存在的链接（可能是重构时引起的），@param指向一个不存在的方法参数，等等不正确的注释。Javadoc只是标注它们为warning，我们还可以生成一个文档。

但是在JDK 8中，Javadoc引入了一个新的feature，叫做doclint，用于检查代码注释是否正确（在生成Javadoc时检查）。Doclint是为了使生成的Javadoc遵循HTML 4.0.1规范，下面是其中的一部分检查规则：

  • 禁止self-closed HTML tags，例如<br/>, <a id=”x”/>
  • 禁止unclosed HTML tags，例如<ul>（缺少</ul>）
  • 禁止不正确的结束标签，例如</br>
  • 不能出现W3C HTML 4.0.1规范以外的异常HTML attributes
  • 不能有多个HTML id attribute
  • 不能有empty HTML href attribute
  • 不正确的标题嵌套，例如类注释应当用<h3>，而不能用<h4>
  • @link链接必须存在
  • @param必须和方法参数名匹配
  • @throws后面必须紧接着一个异常名子

注意：

doclint的这些检查，都是error级别的，有任何问题，都不能生成Javadoc。

关闭doclint

doclint的这种严格检查，默认情况下是打开的，添加-Xdoclint:none便可关闭检查。”-Xdoclint:none”只是JDK 8中有的，如果使用的是JDK 8之前的版本，一定不能有这个，否则maven跑不过。

使用Maven生成Javadoc时，我们可以添加一个global property:

  <properties>
    <additionalparam>-Xdoclint:none</additionalparam>
  </properties>

或者在maven-javadoc-plugin中添加：

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

Gradle没有additional param，Tim Yates和Cedric Champeau建议这样做：

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

总结

对于已经存在的项目，升级成Java 8时，花时间去Fix这些注释的问题，是很不值当的，果断应当将其disable。

默认将doclint打开，对生成文档很不友好，开发者都希望能看到一个生成的文档，纵然它不完美。然而Oracle认为，默认将doclint打开是一个正确选择。