一、综述
1.1 简介
Javadoc 是 Java 自带的一种工具,其可以从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。也就是说,只要在编写程序时以一套特定的标记【Tag】作注释,在程序编写完成后,通过Javadoc就可以同时形成程序的开发文档了。
Java中有三种注释方法:
- //被注释语句
- /*被注释语句*/
- /**被注释语句*/
其中第三种专为 JavaDoc 设计,可以被 JDK 内置的 Javadoc 工具支持和处理。
Javadoc在命令行使用还是比较复杂的,在Eclipse、IntelliJ IDEA等IDE中却比较方便,在命令行使用的麻烦的原因是众多的参数。
但是IDE傻瓜型的操作在有些时候还完成不了想要的任务。这时候,就需要懂得一些参数命令的用法了。
生成 Javadoc 不要求你的Java代码是可编译的,唯一要求的是存在.java文件。
官方提供API帮助文档:
1.2 生成细节
注释文档的格式:
- 注释文档将用来生成HTML格式的代码报告,所以注释文档必须书写在类、域、构造函数、方法、定义之前。
- 注释文档由两部分组成:描述 和 标记。
- 以@开头的是标记。
Javadoc 生成的文档是 HTML 格式,而这些 HTML 格式化的标识符并不是 javadoc 加的,而是我们在写注释的时候写上去的。比如,需要换行时,不是敲入一个回车符,而是写入 <br>,如果要分段,就应该在段前写入 <p>。因此,格式化文档需要在文档注释中添加相应的 HTML 标识。文档注释的正文并不是直接复制到输出文件 (文档的 HTML 文件),而是读取每一行后,删掉前导的 * 号及 * 号以前的空格,再输出到文档的。
注意:文档注释只说明紧接其后的类、属性或者方法。
描述
方法的简单注释:
注意细节:
- 方法的简单注释,是注释第一行最后一个点号“.”之前的,之后的将在下面详细的叙述部分出现。
- 如果方法简述的第一行最后没有点号(哪怕中间有点好),解析的时候会自动查找到下面行中最近的行末尾最后出现的点号。
- IDE相当智能了,但是在格式化代码的时候原本的换行可能会被打乱,因此简单注释的第一行末尾的点号“.”之后使用<br/>进行换行。
详细细节:除了简单叙述外,其它部分的叙述也会出现在下面的详细叙述部分,也就是上面超链接的部分。
标记
标记以@开头:
Tag【标记】 | 描述 | 引入版本 |
标明开发该模块的作者 | 1.0 | |
标明内部是代码示例 | 1.5 | |
代表生成文档的根目录 | 1.3 | |
标明方法或类已过时 | 1.0 | |
对方法可能抛出的异常进行说明【@throws取代】 | 1.0 | |
继承的时候把父类的注释都copy | 1.4 | |
内联链接【代码字体格式】 | 1.2 | |
内联链接【纯文本字体格式】 | 1.4 | |
显示文本【与 | 1.5 | |
对方法参数的说明 | 1.0 | |
对方法返回值的说明 | 1.0 | |
参考转向,也就是相关主题 | 1.0 | |
| 1.2 | |
| 1.2 | |
| 1.2 | |
引入的版本 | 1.1 | |
对方法可能抛出的异常进行说明 | 1.2 | |
值引用 | 1.4 | |
标明该类模块的版本 | 1.0 |
标记的顺序(Order of Tags)
- @author (classes and interfaces only, required)
- @version (classes and interfaces only, required. See footnote 1)
- @param (methods and constructors only)
- @return (methods only)
- @exception (@throws is a synonym added in Javadoc 1.2)
- @see
- @since
- @serial (or @serialField or @serialData)
- @deprecated (see How and When To Deprecate APIs)
可以多次使用标记(Ordering Multiple Tags)
- @author 标记应按时间顺序排列,并用逗号分隔。
- @ param 标记应该在参数声明的顺序列出,这使它更容易在视觉上与声明相匹配的列表。
- @throws 标记 (类同 @exception)应按字母顺序列出的例外的名字。
- @see 标记遵循由近到远,参数由少到多,由上到下的顺序。
@see #field
@see #Constructor(Type, Type...)
@see #Constructor(Type id, Type id...)
@see #method(Type, Type,...)
@see #method(Type id, Type, id...)
@see Class
@see Class#field
@see Class#Constructor(Type, Type...)
@see Class#Constructor(Type id, Type id)
@see Class#method(Type, Type,...)
@see Class#method(Type id, Type id,...)
@see package.Class
@see package.Class#field
@see package.Class#Constructor(Type, Type...)
@see package.Class#Constructor(Type id, Type id)
@see package.Class#method(Type, Type,...)
@see package.Class#method(Type id, Type, id)
@see package
二、详解
2.1 方法及类上注解
@deprecated
- 语法:
@deprecated
deprecated-text - 作用:标明当前方法或类已过时(类名/方法名上会有一个划去的横杠)
@deposated描述的第一句至少应该告诉用户API何时被弃用,以及应该使用什么作为替代。因为只有第一句才会出现在摘要部分和索引中。因此应该使用 @see
标记(针对Javadoc 1.1) 或者 {@link}
标记(针对Javadoc 1.2 or later) 来指向替换的方法:
针对1.2及之后版本:
/**
* @deprecated As of JDK 1.1, replaced by
* {@link #setBounds(int,int,int,int)}
*/
针对1.1版本:
/**
* @deprecated As of JDK 1.1, replaced by setBounds
*
*
* @see #setBounds(int,int,int,int)
*/
@see
- 语法:
@see
- 作用:参考转向,
@see
标记可以创建链接到其他Javadoc文档的交叉引用。
文档注释可以包含任意数量的@see标记,而@see标记会在详细说明中添加"See Also【另请参阅】"列表。@see标记有三种变体,第三种是最常见的。此标记在任何文档注释中都是有效的:概述、包、类、接口、构造函数、方法或字段。
-
@see
"
string" -
@see
<a href="
URL#value">
label</a>
-
@see
package.class#
member label
注意:
- @see 标记后面的字符串必须使用双引号括起来,否则会被当成包名进行解析。
- label 其实是参考列表显示的内容。
- 除第一种外,会在文档中自动生成超链接的条目,但是JavaDoc不会检查及验证指定的超链接是否有效。
- 当前包中的类或者方法以及接口,可以使用类名,或者类名#方法名来指定。
- 非当前包中类或者方法以及接口,我们必须使用完全限定名来指定。
- 默认情况下指定的 package.class.#member 在当前项目中不存在时是不会生成超链接的
/**
* @see String
* @see java.lang.StringBuffer
* @see #str
* @see #str()
* @see #main(String[])
* @see Object#toString()
*/
生成的文档的相关部分如下图:
String 和 StringBuffer 都是在 java.lang 包中,由于这个包是默认导入了的,所以这两个类可以直接写类名,也可以写类全名。str、str() 为同名属性和方法,所以方法名需要用 () 区分。main 是带参数的方法,所以在 () 中指明了参数类型。toString() 虽然在本类中也有 (从 Object 继承的),但我们是想参考 Object 类的 toString() 方法,所以使用了 Object#toString()。
为什么其中只有 str、str() 和 main(String[]) 变成了链接呢?那是因为编译时没有把 java.lang 包或者 Stirng、StringBuffer、Object 三个类的源文件一起加入编译,所以,生成的文档没有关于那三个类的信息,也就不可以建立链接了。后面讲解 javadoc 编译命令的时候还会详细说明。
上例中如果把类中的 str 属性去掉,那么生成的文档又会有什么变化呢?你会发现,原来是 str, str(),而现在变成了 str(), str(),因为 str 属性已经没有了,所以 str 也表示方法 str()。
@since
- 语法:
@since
- 作用:最早使用该方法/类/接口的版本
@since 1.5
{@code}
- 语法:
{@code
text}
- 作用:声明其中的内容是代码注释
注意:使用的时候,必须借助 html 标签<pre>,否则样式是无法保留的。
使用方式:<pre>{@code代码}</pre>
{@docRoot}
- 语法:
{@docRoot}
- 作用:代表生成文档的根目录
<a href="{@docRoot}/copyright.html">
{@link}
- 语法:
{@link
package.class#
member label}
- 作用:插入带有可见文本标签的内联链接,该链接指向引用类的指定包、类或成员名称的文档。这个标记在所有文档注释中都是有效的:概述、包、类、接口、构造函数、方法和字段,包括任何标记的文本部分(例如@return, @param 和 @deprecated)。
注意:与@see标记不同的是,其在使用的地方产生超链接,而不是在"See Also"列表中生成。
Use the {@link #getComponentAt(int, int) getComponentAt} method.
Javadoc会将其转换为如下代码:
Use the <a href="Component.html#getComponentAt(int, int)">getComponentAt</a> method.
{@linkplain}
- 语法:
{@linkplain
package.class#
member label}
- 作用:与{@link}相同,除了链接的标签以纯文本显示,而不是以代码字体显示,当标签是纯文本时很有用。
{@literal}
- 语法:
{@literal
text}
- 作用:显示文本,而不将文本解析为HTML标记或嵌套的Javadoc标记。
{@value}
- 语法:
{@value
package.class#field}
- 作用:值引用
当在静态字段的注释中使用{@value}时(没有任何参数),它将显示该常量的值:
/**
* The value of this constant is {@value}.
*/
public static final String SCRIPT_START = "script";
当在任何doc注释中与参数 package.class#field 字段一起使用时,它将显示指定常量的值:
/**
* Evaluates the script starting with {@value #SCRIPT_START}.
*/
public String evalScript(String script) {
}
2.2 类上注解
@author
- 语法:
@author
- 作用:标明开发该类模块的作者。
@author Fancy<br>Bird
@version
- 语法:
@version
- 作用:该类模块的版本
注意:此标记可以使用多次,但是只有第一次有效。
@serial
- 语法:
@serial
field-description| include | exclude
- 作用:用于默认可序列化字段的doc注释中。
field-description应该解释字段的含义并列出可接受的值。
include
和exclude
参数标识是否应将 类 或 包 包括在序列化窗体页中或将其排除在序列化窗体页之外。如下:
- public 或 protected 类继承了
Serializable
则是 included ,除非类(或者包) 标记为@serial exclude
. - private 或 package-private 类继承了
Serializable
则是excluded,除非类(或者包) 标记为@serial include
.
注意:类级别的@serial标记覆盖包级别的@serial标记。
2.3 方法&接口上注解
@exception @throws
- @throws 以前使用的是 @exception
- 语法:
@throws
- 作用:对方法可能抛出的异常进行说明
@return
- 语法:
@return
- 作用:对方法返回值的说明
@param
- 语法:
@param
- 作用:对方法中的参数进行说明,我们应该针对方法的每一个参数都使用一个该标记。
@serialData
- 语法:
@serialField
{@inheritDoc}
- 语法:
- 作用:表明一个方法是实现一个interface,我们可以使用 {@inheritDoc} 来标识,同时该标记会把接口中的注释复制下来。
三、控制台
虽然使用IDE会非常简单,但是,IDE中还需要使用到各种控制台参数,所以,这里先介绍使用控制台。
首先通过命令,查看控制台辅助信息:
C:\Users\fxb>javadoc -help
用法: javadoc [options] [packagenames] [sourcefiles] [@files]
-overview <file> 从 HTML 文件读取概览文档
-public 仅显示 public 类和成员
-protected 显示 protected/public 类和成员 (默认值)
-package 显示 package/protected/public 类和成员
-private 显示所有类和成员
-help 显示命令行选项并退出
-doclet <class> 通过替代 doclet 生成输出
-docletpath <path> 指定查找 doclet 类文件的位置
-sourcepath <pathlist> 指定查找源文件的位置
-classpath <pathlist> 指定查找用户类文件的位置
-cp <pathlist> 指定查找用户类文件的位置
-exclude <pkglist> 指定要排除的程序包列表
-subpackages <subpkglist> 指定要递归加载的子程序包
-breakiterator 计算带有 BreakIterator 的第一个语句
-bootclasspath <pathlist> 覆盖由引导类加载器所加载的
类文件的位置
-source <release> 提供与指定发行版的源兼容性
-extdirs <dirlist> 覆盖所安装扩展的位置
-verbose 输出有关 Javadoc 正在执行的操作的信息
-locale <name> 要使用的区域设置, 例如 en_US 或 en_US_WIN
-encoding <name> 源文件编码名称
-quiet 不显示状态消息
-J<flag> 直接将 <flag> 传递到运行时系统
-X 输出非标准选项的提要
通过标准 doclet 提供:
-d <directory> 输出文件的目标目录
-use 创建类和程序包用法页面
-version 包含 @version 段
-author 包含 @author 段
-docfilessubdirs 递归复制文档文件子目录
-splitindex 将索引分为每个字母对应一个文件
-windowtitle <text> 文档的浏览器窗口标题
-doctitle <html-code> 包含概览页面的标题
-header <html-code> 包含每个页面的页眉文本
-footer <html-code> 包含每个页面的页脚文本
-top <html-code> 包含每个页面的顶部文本
-bottom <html-code> 包含每个页面的底部文本
-link <url> 创建指向位于 <url> 的 javadoc 输出的链接
-linkoffline <url> <url2> 利用位于 <url2> 的程序包列表链接至位于 <ur
的文档
-excludedocfilessubdir <name1>:.. 排除具有给定名称的所有文档文件子目录。
-group <name> <p1>:<p2>.. 在概览页面中, 将指定的程序包分组
-nocomment 不生成说明和标记, 只生成声明。
-nodeprecated 不包含 @deprecated 信息
-noqualifier <name1>:<name2>:... 输出中不包括指定限定符的列表。
-nosince 不包含 @since 信息
-notimestamp 不包含隐藏时间戳
-nodeprecatedlist 不生成已过时的列表
-notree 不生成类分层结构
-noindex 不生成索引
-nohelp 不生成帮助链接
-nonavbar 不生成导航栏
-serialwarn 生成有关 @serial 标记的警告
-tag <name>:<locations>:<header> 指定单个参数定制标记
-taglet 要注册的 Taglet 的全限定名称
-tagletpath Taglet 的路径
-charset <charset> 用于跨平台查看生成的文档的字符集。
-helpfile <file> 包含帮助链接所链接到的文件
-linksource 以 HTML 格式生成源文件
-sourcetab <tab length> 指定源中每个制表符占据的空格数
-keywords 使程序包, 类和成员信息附带 HTML 元标记
-stylesheetfile <path> 用于更改生成文档的样式的文件
-docencoding <name> 指定输出的字符编码
3.1 语法
javadoc [ options ] [ packagenames ] [ sourcefilenames ] [ -subpackages pkg1:pkg2:... ] [ @argfiles ]
注意:Arguments can be in any order.(理解:参数没有顺序要求是指的是options的参数,但是包名,以及源文件名等的顺序还是要与上述相同的。)
options(命令行选项)
上面已经罗列的非常详细了,不过最好是通过直接在控制台查询比较好,因为版本之间会出现细微差别。
下面罗列出常用的命令行选项:
- 设置源码编码方式:-encoding UTF-8
- 指定输出的字符编码:-charset UTF-8
注意:如果出现乱码,这两个设置必须同时正确存在。
- 自定输出的路径:-d
- 使用的语言环境:-locale zh_CN
- 指定标题栏标题文字:-windowtitle <text>
- 包含概览页面的标题:-doctitle <html-code>
- 包含每个页面的页眉文本:-header <html-code>
- 包含每个页面的页脚文本:-footer <html-code>
- 包含每个页面的顶部文本:-top <html-code>
- 包含每个页面的底部文本:-bottom <html-code>
- 指定查找源文件的位置:-sourcepath <pathlist>
- 指定要递归加载的子程序包:-subpackages <subpkglist>
Eclipse生成的注释文档中文乱码时,若项目采用的是 UTF-8 的编码时,添加参数:-encoding UTF-8 -charset UTF-8 即可。
packagenames(包名称)
包名称与Java的使用规则类同,都是通过点号进行分割,例如:java.lang java.lang.reflect。
注意:你必须分别指明你要生成文档的文件夹,因为 Wildcards(通配符)是无法使用的,Javadoc tool会通过递归的方式,遍寻子文件夹。
You may split the source files for a single package among two such directory trees located at different places,as long as -sourcepath points to them both – for example src1\java\awt\color and src2\java\awt\color.
你可以将原文件分割成后放在两个不同的目录树下,只要通过-sourcepath指向他们两个就可以了。(例如:src1\java\awt\color and src2\java\awt\color)
You can run javadoc either by changing directories (with cd
) or by using -sourcepath
option.
你可以通过改变目录(使用cd命令)或者使用 -sourcepath 选项。
提示:cd命令是Windows控制台中的进入指定目录的命令(其它系统暂且不知)。
示例一:Run recursively starting from one or more packages(利用递归的方式从一个或多个包处运行)
javadoc -d \home\html -sourcepath \home\src -subpackages java -exclude java.net:java.lang
This example uses -sourcepath so javadoc can be run from any directory and -subpackages (a new 1.4 option) for recursion. It traverses the subpackages of the java directory excluding packages rooted at java.net and java.lang. Notice this excludes java.lang.ref, a subpackage of java.lang).
因为这个实例使用了-sourcepath选项,所以可以运行在任意文件夹下,并且使用了-subpackages(1.4新增选项)来进行递归。Javadoc工具将会便利java包中的所包含的各各包,但是排除-exclude选项所指定的java.net和java.lang包以及其下面包含的子包。
如果想要对其它包树也进行遍历,则只需要在-subpackages的参数上附加上即可,例如:such as java:javax:org.xml.sax
注意:附加时,要用冒号进行分割。
实例二:Run on explicit packages after changing to the "root" source directory(在改变根目录后,运行在明确的包下)
C:> cd C:\home\src\
C:> javadoc -d C:\home\html java.awt java.awt.event
注意:这种运行方式指定参数时,与上面的方式有细微差别,声明要生成文档的目录的时候此处采用的是空格隔开,上面是采用附加的方式。
示例三: Run from any directory on explicit packages in a single directory tree(一个目录树)
C:> javadoc -d C:\home\html -sourcepath C:\home\src java.awt java.awt.event
在这种情况下,你可以运行在任意目录下。因为通过-sourcepath指明了顶层包的位置,以及要生成的文档的包。
示例四: Run from any directory on explicit packages in multiple directory trees(多个目录树)
C:> javadoc -d C:\home\html -sourcepath C:\home\src1;C:\home\src2 java.awt java.awt.event
注意:指明多个目录树的时候,一定要用分好隔开。
sourcefilenames(源文件名称)
This is useful for test files and template files The path that precedes the source file name determines where javadoc will look for the file.(The Javadoc tool does not use -sourcepath to look for these source file names.) Relative paths are relative to the current directory, so passing in Button.java is identical to ./Button.java.
多个源文件可以用空格隔开,每一个都可以使用路径和通配符的方式。Javadoc tool 将会处理每一个以“.java”结尾的文件,当文件名去除后缀.java以后,仍然还是一个合法的类名时,将会生成相应的文档文件。因此,我们可以使用破折号(例如X-Buffer)或者其他非法的字符命名文件来阻止生成帮助文档,当然改后缀名也是可以的。(Javadoc toll不会使用-sourcepath去查找源文件的名称)相对路径是相对于当前的路径。传入Button.java相当于./java.
The second way to run the Javadoc tool is by passing in one or more source files (.java). You can run javadoc either of the following two ways – by changing directories (with cd) or by fully-specifying the path to the .java files. Relative paths are relative to the current directory. The -sourcepath option is ignored when passing in source files. You can use command line wildcards, such as asterisk (*), to specify groups of classes.
-sourcepath选项将会被忽略。你可以使用命令行通配符,如使用星号(*)来指定类,例如:/home/src/java/awt/Graphics*.java
示例一: Changing to the source directory(改变到源目录)
进入到你的源文件目录下,然后运行javadoc,并指定一个或多个你想要生成文档的源文件名字。
C:> cd C:\home\src\java\awt
C:> javadoc -d C:\home\html Button.java Canvas.java Graphics*.java
因为指定的是源文件而不是包名作为参数传递给javadoc,所以生成的Html的文档只包含两部分框架——类和主页列表。
实例二:Changing to the package root directory(改变到根目录)
这是一个记录个人开发文档的很好地方法,进入到指定的根目录,然后并通过相对路径来制定文件。
C:> cd C:\home\src
C:> javadoc -d \home\html java\awt\Button.java java\applet\Applet.java
实例三:From any directory(从任意文件夹)
在这种情况下,不管当前目录在哪里,通过指定绝对路径(或相对于当前目录路径)来运行Javadoc来生成说明文档。
C:> javadoc -d C:\home\html C:\home\src\java\awt\Button.java C:\home\src\java\awt\Graphics*.java
上面的例子是通过包或者详细的文件名的方式的方式生成说明文档,我们也可以使用-sourcepath来指定包的路径而不是指定到单独的类路径。
下面的例子是融合上面两种方式:
C:> javadoc -d C:\home\html -sourcepath C:\home\src java.awt C:\home\src\java\applet\Applet.java
这个例子会对java.awt文件夹进行遍历生成,并对绝对的路径指定的文件进行生成帮助文档。
-subpackages pkg1:pkg2:...
Generates documentation from source files in the specified packages and recursively in their subpackages. An alternative to supplying packagenames or sourcefilenames.
生成文档时从指定源文件包来进行递归子包。
@argfiles
One or more files that contain a list of Javadoc options, packagenames and sourcefilenames in any order. Wildcards (*) and -J options are not allowed in these files.
3.2 细节
不必指定源文件名称的三种情况:
- 指定包名称
- 使用子包
- 使用通配符
在上述情况中,必须要满足的条件:
- 文件名称必须以.java结尾,并且文件名是一个合法的类名。
- 相对于根目录路径需要是一个合法的包名(以点号进行分割的形式)
- 包名称必须是一个合法的
四、IDE集成
Export(导出) →找到Java下的Javadoc → 设置好各个选项 → 设置控制台的参数列表:
Eclipse Java注释模板设置详解
设置注释模板的入口: Window → Preference → Java → Code Style →Code Template 然后展开Comments节点就是所有需设置注释的元素。