3.1.2 Java9增强文档注释
3.1.2 Java9增强文档注释
Java语言还提供了一种功能更强大的注释形式:文档注释。如果编写Java源代码时添加了合适的文档注释,然后通过JDK提供的javadoc工具可以直接将源代码里的文档注释提取成一份系统的API文档。Java提供了大量的基础类,因此Oracle也为这些基础类提供了相应的API文档,用于告诉开发者如何使用这些类,以及这些类里包含的方法。
下载API文档
进入java SE下载页面:
https://www.oracle.com/technetwork/java/javase/downloads/index.html
将页面拉到最下面就可以看到文档的下载链接
1 | https://www.oracle.com/technetwork/java/javase/documentation/jdk11-doc-downloads-5097203.html |
然后进入文档下载页面Java9对API文档进行了增强,Java9为API文档增加了一个搜索框,如图3.2中右上角所示,用户可以通过该搜索框快速查找指定的Java类。
Java9的API子集
Java 9将API文档分成3个子集。
Java SE:该子集的API文档主要包含Java SE的各种类JDK:该子集的API文档主要包含JDK的各种工具类Java FX:该子集的API文档主要包含Java FX的各种类
哪些文档注释会被javadoc处理
由于文档注释是用于生成API文档的,而API文档主要用于说明类、方法、成员变量的功能。因此,javadoc工具只处理文档源文件在类、接口、方法、成员变量、构造器和内部类之前的注释,忽略其他地方的文档注释。
而且**javadoc工具默认只处理以public或protected修饰的类、接口、方法、成员变量、构造器和内部类之前的文档注释**。
API文档类似于产品的使用说明书,通常使用说明书只需要介绍那些暴露的、供用户使用的部分。Java类中只有以public或protected修饰的内容才是希望暴露给別人使用的内容,因此javadoc默认只处理public或protected修饰的内容。
如何提取私有成员的文档注释
如果开发者确实希望javadoc工具可以提取private修饰的内容,则可以在使用javadoc工具时增加-private选项
文档注释符号
文档注释以斜线后紧跟两个星号(/**)开始,以星号后紧跟一个斜线(*/)结束,中间部分全部都是文档注释,会被提取到API文档中。Java9的API文档已经支持HTML5规范,因此为了得到完全兼容HTML5的API文档,必须保证文档注释中的内容完全兼容HTML5规范。
生成API
编写好上面的Java程序后,就可以使用javadoc工具提取这程序中的文档注释来生成API文档了。javadoc命令的基本用法如下:
javadoc语法格式
1 | javadoc 选项 Java源文件|包 |
javadoc命令可对源文件、包生成API文档.
javadoc选项
在上面的语法格式中,Java源文件可以支持通配符,例如,使用*.java来代表当前路径下所有的Java源文件。javadoc的常用选项有如下几个。
-d <Directory>:该选项用于指定保存生成的API文档的目录下。-windowtitle <text>:该选项指定一个字符串,用于设置API文档的浏览器窗口标题-doctitle <html-code>:该选项指定一个HTML格式的文本,用于指定概述页面的标题。只有对处于多个包下的源文件来生成API文档时,才有概述页面。-header <html-code>:该选项指定一个HTML格式的文本,包含每个页面的页眉。
查看javadoc帮助文档
除此之外,javadoc命令还包含了大量其他选项,读者可以通过在命令行窗口执行javadoc -help来查看javadoc命令的所有选项。
在命令行窗口执行如下命令来为刚刚编写的两个Java程序生成API文档:
1 | javadoc -d apidoc -windowtitle 测试 -doctitle 学习 javadoc 工具的测试 API文档 -header 我的类 *Test.java |
常用javadoc标记
除此之外,如果希望javadoc工具生成更详细的文档信息,例如为方法参数、方法返回值等生成详细的说明信息,则可利用javadoc标记。常用的javadoc标记如下：
@author:指定Java程序的作者@version:指定源文件的版本。@deprecated:不推荐使用的方法。@param:方法的参数说明信息@return:方法的返回值说明信息。@see:“参见”,用于指定交叉参考的内容。@exception:抛出异常的类型。@throws:抛出的异常,和@exception同义。
可以出现在 类或者接口 的文档注释
需要指出的是,这些标记的使用是有位置限制的。上面这些标记可以出现在类或者接口的文档注释中的有@see、 @deprecated、 @author、@version等;
可以出现在 方法或构造器 的文档注释
可以出现在方法或构造器的文档注释中的有@see、@deprecated、@param、@return、@throws和@exception等;
可以出现在成员变量的文档注释
可以出现在成员变量的文档注释中的有@see和@deprecated等。
javadoc不会默认提取author和author注释
javadoc工具默认不会提取@author和@author两个标记的信息,如果需要提取这两个标记的信息,应该在使用javadoc工具时指定-author和-version两个选项。
为了能提取到文档中的@author和@version等标记信息,在使用javadoc工具时增加-author和-version两个选项,即按如下格式来运行javadoc命令:
1 | javadoc -d apidoc -windowtitle 测试 -doctitle 学习 javadoc工具的测试 API 文档 -header 我的类 -version -author *Test.java |
上面命令将会提取Java源程序中的author和vcrsion两个标记的信息。除此之外,还会提取@param和@return标记的信息.
包描述文件
API文档中的包注释并不是直接放在Java源文件中的,而是必须另外指定,通常通过一个标准的HTML5文件来提供包注释,这个文件被称为包描述文件。包描述文件的文件名通常是package.html,并与该包下所有的Java源文件放在一起,javadoc工具会自动寻找对应的包描述文件,并提取该包描述文件中的<body>元素里的内容,作为该包的描述信息。
程序示例
目录结构
1 | G:\Desktop\随书源码\疯狂Java讲义(第4版)光盘\codes\03\3.1\package |
该项目有两个文件夹(包):
first文件夹:包含**JavadocTestJava**文件(该Java类的包为first),对应包描述文件package.htmlsecond文件夹:包含Test.java文件和JavadocTagTest.java文件(这两个Java类的包为yeku),对应包描述文件package.html
在命令行窗口进入first和second所在路径(package路径),执行如下命令:
1 | javadoc -d apidoc -windowtitle 测试 -doctitle 学习javadoc工具的测试API文档 -header 我的类 -version -author first second |
上面命令指定对first包和second包来生成API文档,而不是对Java源文件来生成API文档,这也是允许的。其中first包和second包下面都提供了对应的包描述文件。
如果需要设置包描述信息,则需要将Java源文件按包结构来组织存放,这不是问题。实际上,当编写Java源文件时,通常总会按包结构来组织存放Java源文件,这样更有利于项目的管理。
现在生成的API文档已经非常“专业”了,和系统提供的APⅠ文档基本类似。关于Java文档注释和javadoc工具使用的介绍也基本告一段落了。