关闭JDK8中的doclint

By | 2017年3月1日

原文: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打开是一个正确选择。