Java 9 新特性 – 改进 JavaDocs

最新推荐文章于 2025-12-21 21:47:42 发布

原创最新推荐文章于 2025-12-21 21:47:42 发布 · 118 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#java

java9 专栏收录该内容

17 篇文章

订阅专栏

本文介绍了Java中JavaDoc文档格式的变化。一直以来JavaDoc使用HTML 4格式，Java 9开始支持HTML 5，但非默认。文中展示了旧的HTML 4格式下创建文件并使用javadoc命令输出文档的过程，也介绍了使用 -html5 选项指定输出HTML 5格式的方法。

一直以来，Java 生成的文档 JavaDoc 一直使用的都是 HTML 4 格式，这次 Java 9 良心大大的发现，使用了 HTML 5 ，但还不是默认的，如果要输出 HTML 5 格式，还必须在命令行程序中添加 -html5 选项。

旧的 JavaDoc 文档格式

我们先在当前工作区，例如我的是 D:\devops\java9 的 src 目录下创建一个文件 JavaDocTester.java ，内容如下

/**
  * @author MahKumar
  * @version 0.1
*/
public class JavaDocTester {
   /**
      * 默认的方法用于输出 Hello World 
      * <p>Hello world</p>
      * @param args 命令行参数
   */
   public static void main(String []args) {
      System.out.println("Hello World");
   }
}

然后我们就可以使用 javadoc 命令输出该类的文档

[penglei@ddkk.com java9]$ javadoc -d . JavaDocTester.java 
正在加载源文件JavaDocTester.java...
正在构造 Javadoc 信息...
javadoc: 警告 - 未指定要使用的 HTML 版本。
默认值当前为 HTML 4.01，但在未来发行版中
将更改为 HTML5。要隐藏此警告，请使用 -html4 
或 -html5 选项，指定要由此 doclet 生成的、
在文档注释中使用的 HTML 版本。
标准 Doclet 版本 10.0.2
正在构建所有程序包和类的树...
正在生成./JavaDocTester.html...
正在生成./package-frame.html...
正在生成./package-summary.html...
正在生成./package-tree.html...
正在生成./constant-values.html...
正在构建所有程序包和类的索引...
正在生成./overview-tree.html...
正在生成./index-all.html...
正在生成./deprecated-list.html...
正在构建所有类的索引...
正在生成./allclasses-frame.html...
正在生成./allclasses-frame.html...
正在生成./allclasses-noframe.html...
正在生成./allclasses-noframe.html...
正在生成./index.html...
正在生成./help-doc.html...
1 个警告

可以看到 javadoc 默认使用的还是 html 4.0.1 版本

如果我们翻看源码，就可以看到 HTML 4.0.1 的文档声明了

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

新的 JavaDoc 文档格式

从上面的输出结果中还可以看出，可以使用 -html5 选项指定输出结果为 HTML 5 ，我们来试一试吧

[penglei@ddkk.com java9]$ javadoc -html5  -d . JavaDocTester.java 
正在加载源文件JavaDocTester.java...
正在构造 Javadoc 信息...
标准 Doclet 版本 10.0.2
正在构建所有程序包和类的树...
正在生成./JavaDocTester.html...
正在生成./package-frame.html...
正在生成./package-summary.html...
正在生成./package-tree.html...
正在生成./constant-values.html...
正在构建所有程序包和类的索引...
正在生成./overview-tree.html...
正在生成./index-all.html...
正在生成./deprecated-list.html...
正在构建所有类的索引...
正在生成./allclasses-frame.html...
正在生成./allclasses-frame.html...
正在生成./allclasses-noframe.html...
正在生成./allclasses-noframe.html...
正在生成./index.html...
正在生成./help-doc.html...

当使用HTML 5 格式时，输出日志都变少了…

然后打开当前目录下的 index.html ，可以发现页面长的还是一样

但如果查看页面的源码，就会发现已经使用了 HTML 5 文档类型声明了