【java9】java9新特性之改进JavaDocs

Java9在JavaDocs方面的主要新特性是，其输出现在符合兼容HTML5标准。在之前的版本中，默认的HTML版本是 HTML4.01，但在Java9及之后的版本中，JavaDocs命令行工具将默认使用HTML5作为输出标记语言。这意味着，使用JavaDocs工具生成的文档将具有更现代、更丰富的样式和功能，同时保持与现有HTML5浏览器的兼容性。

此外，JavaDocs的输出结构也保持不变，仍然由三个框架组成的结构构成，即使是以HTML5输出的Java帮助文档也保持相同的结构。这意味着，尽管在底层技术上有所更新，但生成的文档对于用户来说仍然是非常熟悉和直观的。

总的来说，Java9在JavaDocs方面的改进使得生成的文档更加现代化和兼容，同时也保持了用户的体验一致性。这些改进有助于提高文档的可读性和可用性，使得开发人员更容易理解和使用Java API。

java8生成的html4文档

例如有下面一个简单测试类：

package com.morris.java9;

/**
 * <p>This is a test doc class.</p>
 *
 * @author morris131
 * @version 1.0.0
 */
public class DocDemo {

    /**
     * <p> get the age of user by the name of user.</p>
     *
     * @param name the name of user
     * @return the age of user
     */
    public int getAgeByName(String name) {
        return 18;
    }
}

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

$ javadoc -d src/main/resources/java8-doc-html4 src/main/java/com/morris/java
9/DocDemo.java
Loading source file src/main/java/com/morris/java9/DocDemo.java...
Constructing Javadoc information...
Creating destination directory: "src/main/resources/java8-doc-html4/"
Standard Doclet version 1.8.0_401
Building tree for all the packages and classes...
Generating src/main/resources/java8-doc-html4/com/morris/java9/DocDemo.html...
Generating src/main/resources/java8-doc-html4/com/morris/java9/package-frame.html...
Generating src/main/resources/java8-doc-html4/com/morris/java9/package-summary.html...
Generating src/main/resources/java8-doc-html4/com/morris/java9/package-tree.html...
Generating src/main/resources/java8-doc-html4/constant-values.html...
Building index for all the packages and classes...
Generating src/main/resources/java8-doc-html4/overview-tree.html...
Generating src/main/resources/java8-doc-html4/index-all.html...
Generating src/main/resources/java8-doc-html4/deprecated-list.html...
Building index for all classes...
Generating src/main/resources/java8-doc-html4/allclasses-frame.html...
Generating src/main/resources/java8-doc-html4/allclasses-noframe.html...
Generating src/main/resources/java8-doc-html4/index.html...
Generating src/main/resources/java8-doc-html4/help-doc.html...

打开index.html的源码，就可以看到HTML4.01的文档声明了：

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

可以看到javadoc默认使用的是HTML4.0.1版本。

java9生成html4文档

还是上面的测试类，使用java9来生成生成html4文档：

$ javadoc -d src/main/resources/java9-doc-html4 src/main/java/com/morris/java9/DocDemo.java
Loading source file src/main/java/com/morris/java9/DocDemo.java...
Constructing Javadoc information...
Standard Doclet version 9.0.4
Building tree for all the packages and classes...
Generating src/main/resources/java9-doc-html4/com/morris/java9/DocDemo.html...
Generating src/main/resources/java9-doc-html4/com/morris/java9/package-frame.html...
Generating src/main/resources/java9-doc-html4/com/morris/java9/package-summary.html...
Generating src/main/resources/java9-doc-html4/com/morris/java9/package-tree.html...
Generating src/main/resources/java9-doc-html4/constant-values.html...
Building index for all the packages and classes...
Generating src/main/resources/java9-doc-html4/overview-tree.html...
Generating src/main/resources/java9-doc-html4/index-all.html...
Generating src/main/resources/java9-doc-html4/deprecated-list.html...
Building index for all classes...
Generating src/main/resources/java9-doc-html4/allclasses-frame.html...
Generating src/main/resources/java9-doc-html4/allclasses-frame.html...
Generating src/main/resources/java9-doc-html4/allclasses-noframe.html...
Generating src/main/resources/java9-doc-html4/allclasses-noframe.html...
Generating src/main/resources/java9-doc-html4/index.html...
Generating src/main/resources/java9-doc-html4/help-doc.html...

打开index.html的源码，就可以看到HTML4.01的文档声明了：

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

可以看到javadoc默认使用的是HTML4.0.1版本。

java9生成html5文档

还是上面的测试类，使用-html5选项指定输出结果为HTML 5：

$ javadoc -html5 -d src/main/resources/java9-doc-html5 src/main/java/com/morris/java9/DocDemo.java
Loading source file src/main/java/com/morris/java9/DocDemo.java...
Constructing Javadoc information...
Standard Doclet version 9.0.4
Building tree for all the packages and classes...
Generating src/main/resources/java9-doc-html5/com/morris/java9/DocDemo.html...
Generating src/main/resources/java9-doc-html5/com/morris/java9/package-frame.html...
Generating src/main/resources/java9-doc-html5/com/morris/java9/package-summary.html...
Generating src/main/resources/java9-doc-html5/com/morris/java9/package-tree.html...
Generating src/main/resources/java9-doc-html5/constant-values.html...
Building index for all the packages and classes...
Generating src/main/resources/java9-doc-html5/overview-tree.html...
Generating src/main/resources/java9-doc-html5/index-all.html...
Generating src/main/resources/java9-doc-html5/deprecated-list.html...
Building index for all classes...
Generating src/main/resources/java9-doc-html5/allclasses-frame.html...
Generating src/main/resources/java9-doc-html5/allclasses-frame.html...
Generating src/main/resources/java9-doc-html5/allclasses-noframe.html...
Generating src/main/resources/java9-doc-html5/allclasses-noframe.html...
Generating src/main/resources/java9-doc-html5/index.html...
Generating src/main/resources/java9-doc-html5/help-doc.html...