JavaDoc生成API详解

一、综述

1.1 简介

  Javadoc 是 Java 自带的一种工具，其可以从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。也就是说，只要在编写程序时以一套特定的标记【Tag】作注释，在程序编写完成后，通过Javadoc就可以同时形成程序的开发文档了。
Java中有三种注释方法：

• //被注释语句
• /*被注释语句*/
• /**被注释语句*/

  其中第三种专为 JavaDoc 设计，可以被 JDK 内置的 Javadoc 工具支持和处理。
  Javadoc在命令行使用还是比较复杂的，在Eclipse、IntelliJ IDEA等IDE中却比较方便，在命令行使用的麻烦的原因是众多的参数。

  但是IDE傻瓜型的操作在有些时候还完成不了想要的任务。这时候，就需要懂得一些参数命令的用法了。
  生成 Javadoc 不要求你的Java代码是可编译的，唯一要求的是存在.java文件。

官方提供API帮助文档：

• JDK7：javadoc - The Java API Documentation Generator
• JDK8：javadoc

1.2 生成细节

注释文档的格式：

• 注释文档将用来生成HTML格式的代码报告，所以注释文档必须书写在类、域、构造函数、方法、定义之前。
• 注释文档由两部分组成：描述 和 标记。
• 以@开头的是标记。

  Javadoc 生成的文档是 HTML 格式，而这些 HTML 格式化的标识符并不是 javadoc 加的，而是我们在写注释的时候写上去的。比如，需要换行时，不是敲入一个回车符，而是写入
，如果要分段，就应该在段前写入

。因此，格式化文档需要在文档注释中添加相应的 HTML 标识。文档注释的正文并不是直接复制到输出文件 (文档的 HTML 文件)，而是读取每一行后，删掉前导的 * 号及 * 号以前的空格，再输出到文档的。

注意：文档注释只说明紧接其后的类、属性或者方法。

描述

方法的简单注释：

注意细节：

1. 方法的简单注释，是注释第一行最后一个点号“.”之前的，之后的将在下面详细的叙述部分出现。
2. 如果方法简述的第一行最后没有点号（哪怕中间有点好），解析的时候会自动查找到下面行中最近的行末尾最后出现的点号。
3. IDE相当智能了，但是在格式化代码的时候原本的换行可能会被打乱，因此简单注释的第一行末尾的点号“.”之后使用
   进行换行。

详细细节：除了简单叙述外，其它部分的叙述也会出现在下面的详细叙述部分，也就是上面超链接的部分。

标记

标记以@开头：

Tag【标记】	描述	引入版本
@author	标明开发该模块的作者	1.0
{@code}	标明内部是代码示例	1.5
{@docRoot}	代表生成文档的根目录	1.3
@deprecated	标明方法或类已过时	1.0
@exception	对方法可能抛出的异常进行说明【@throws取代】	1.0
{@inheritDoc}	继承的时候把父类的注释都copy	1.4
{@link}	内联链接【代码字体格式】	1.2
{@linkplain}	内联链接【纯文本字体格式】	1.4
{@literal}	显示文本【与 标签类同】	1.5
@param	对方法参数的说明	1.0
@return	对方法返回值的说明	1.0
@see	参考转向，也就是相关主题	1.0
@serial		1.2
@serialData		1.2
@serialField		1.2
@since	引入的版本	1.1
@throws	对方法可能抛出的异常进行说明	1.2
{@value}	值引用	1.4
@version	标明该类模块的版本	1.0

标记的顺序（Order of Tags）

1. @author (classes and interfaces only, required)
2. @version (classes and interfaces only, required. See footnote 1)
3. @param (methods and constructors only)
4. @return (methods only)
5. @exception (@throws is a synonym added in Javadoc 1.2)
6. @see
7. @since
8. @serial (or @serialField or @serialData)
9. @deprecated (see  How and When To Deprecate APIs)

可以多次使用标记（Ordering Multiple Tags）

1. @author 标记应按时间顺序排列，并用逗号分隔。
2. @ param 标记应该在参数声明的顺序列出，这使它更容易在视觉上与声明相匹配的列表。
3. @throws 标记 (类同 @exception)应按字母顺序列出的例外的名字。
4. @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

1. 语法：@see  reference
2. 作用：参考转向，@see标记可以创建链接到其他Javadoc文档的交叉引用。

文档注释可以包含任意数量的@see标记，而@see标记会在详细说明中添加"See Also【另请参阅】"列表。@see标记有三种变体，第三种是最常见的。此标记在任何文档注释中都是有效的：概述、包、类、接口、构造函数、方法或字段。

1. @see "string"
2. @see label
3. @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-text
• 作用：最早使用该方法/类/接口的版本

@since 1.5

{@code}

• 语法：{@code  text}
• 作用：声明其中的内容是代码注释

注意：使用的时候，必须借助 html 标签

，否则样式是无法保留的。
 
  
使用方式：
{@code代码}
 
  
{@docRoot}
 
  
 
   
语法：{@docRoot}
 
   
作用：代表生成文档的根目录
 
  
 
  
 
  
{@link}
 
  
 
   
语法：{@link  package.class#member  label}
 
   
作用：插入带有可见文本标签的内联链接，该链接指向引用类的指定包、类或成员名称的文档。这个标记在所有文档注释中都是有效的：概述、包、类、接口、构造函数、方法和字段，包括任何标记的文本部分(例如@return, @param 和 @deprecated)。
 
  
 
  
注意：与@see标记不同的是，其在使用的地方产生超链接，而不是在"See Also"列表中生成。
 
  
Use the {@link #getComponentAt(int, int) getComponentAt} method.
Javadoc会将其转换为如下代码：
Use the getComponentAt 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  name-text
 
   
作用：标明开发该类模块的作者。
 
  
 
  
@author Fancy
Bird
 
  
@version
 
  
 
   
语法：@version  version-text
 
   
作用：该类模块的版本
 
  
 
  
注意：此标记可以使用多次，但是只有第一次有效。
 
  
@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  class-name  description
 
   
作用：对方法可能抛出的异常进行说明
 
  
 
  
@return
 
  
 
   
语法：@return  description
 
   
作用：对方法返回值的说明
 
  
 
  
@param
 
  
 
   
语法：@param  parameter-name description
 
   
作用：对方法中的参数进行说明，我们应该针对方法的每一个参数都使用一个该标记。
 
  
 
  
@serialData
 
  
 
   
语法：@serialField  field-name  field-type  field-description
 
  
 
  
{@inheritDoc}
 
  
 
   
语法：
 
   
作用：表明一个方法是实现一个interface，我们可以使用 {@inheritDoc} 来标识，同时该标记会把接口中的注释复制下来。 
 
  
 
  
三、控制台
 
  
虽然使用IDE会非常简单，但是，IDE中还需要使用到各种控制台参数，所以，这里先介绍使用控制台。
 
  
首先通过命令，查看控制台辅助信息：
 
  
C:\Users\fxb>javadoc -help
用法: javadoc [options] [packagenames] [sourcefiles] [@files]
  -overview                  从 HTML 文件读取概览文档
  -public                          仅显示 public 类和成员
  -protected                       显示 protected/public 类和成员 (默认值)
  -package                         显示 package/protected/public 类和成员
  -private                         显示所有类和成员
  -help                            显示命令行选项并退出
  -doclet                   通过替代 doclet 生成输出
  -docletpath                指定查找 doclet 类文件的位置
  -sourcepath            指定查找源文件的位置
  -classpath             指定查找用户类文件的位置
  -cp                    指定查找用户类文件的位置
  -exclude                指定要排除的程序包列表
  -subpackages         指定要递归加载的子程序包
  -breakiterator                   计算带有 BreakIterator 的第一个语句
  -bootclasspath         覆盖由引导类加载器所加载的
                                   类文件的位置
  -source                 提供与指定发行版的源兼容性
  -extdirs                覆盖所安装扩展的位置
  -verbose                         输出有关 Javadoc 正在执行的操作的信息
  -locale                    要使用的区域设置, 例如 en_US 或 en_US_WIN
  -encoding                  源文件编码名称
  -quiet                           不显示状态消息
  -J                         直接将  传递到运行时系统
  -X                               输出非标准选项的提要

通过标准 doclet 提供:
  -d                    输出文件的目标目录
  -use                             创建类和程序包用法页面
  -version                         包含 @version 段
  -author                          包含 @author 段
  -docfilessubdirs                 递归复制文档文件子目录
  -splitindex                      将索引分为每个字母对应一个文件
  -windowtitle               文档的浏览器窗口标题
  -doctitle             包含概览页面的标题
  -header               包含每个页面的页眉文本
  -footer               包含每个页面的页脚文本
  -top                  包含每个页面的顶部文本
  -bottom               包含每个页面的底部文本
  -link                       创建指向位于  的 javadoc 输出的链接
  -linkoffline          利用位于  的程序包列表链接至位于 :.. 排除具有给定名称的所有文档文件子目录。
  -group  :..        在概览页面中, 将指定的程序包分组
  -nocomment                       不生成说明和标记, 只生成声明。
  -nodeprecated                    不包含 @deprecated 信息
  -noqualifier ::... 输出中不包括指定限定符的列表。
  -nosince                         不包含 @since 信息
  -notimestamp                     不包含隐藏时间戳
  -nodeprecatedlist                不生成已过时的列表
  -notree                          不生成类分层结构
  -noindex                         不生成索引
  -nohelp                          不生成帮助链接
  -nonavbar                        不生成导航栏
  -serialwarn                      生成有关 @serial 标记的警告
  -tag ::
 指定单个参数定制标记
  -taglet                          要注册的 Taglet 的全限定名称
  -tagletpath                      Taglet 的路径
  -charset                用于跨平台查看生成的文档的字符集。
  -helpfile                  包含帮助链接所链接到的文件
  -linksource                      以 HTML 格式生成源文件
  -sourcetab           指定源中每个制表符占据的空格数
  -keywords                        使程序包, 类和成员信息附带 HTML 元标记
  -stylesheetfile            用于更改生成文档的样式的文件
  -docencoding               指定输出的字符编码
 
  
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  
 
   
包含概览页面的标题：-doctitle  
 
   
包含每个页面的页眉文本：-header  
 
   
包含每个页面的页脚文本：-footer  
 
   
包含每个页面的顶部文本：-top  
 
   
包含每个页面的底部文本：-bottom  
 
   
指定查找源文件的位置：-sourcepath  
 
   
指定要递归加载的子程序包：-subpackages  
 
  
 
  
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（源文件名称）
 
  
  A series of source file names, separated by spaces, each of which can begin with a path and contain a wildcard such as asterisk (*). The Javadoc tool will process every file whose name ends with ".java", and whose name, when stripped of that suffix, is actually a legal class name (see information about Identifiers in the Java Language Specification). Therefore, you can name files with dashes (such as X-Buffer), or other illegal characters, to prevent them from being documented.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.
 
  
  第二种方法运行Javadoc tool是通过指定一个或多个源文件(. java)。你可以运行Javadoc通过两种方式，分别是改变目录（使用cd命令）或者使用fully-specifying（绝对路径及相对路径）路径来制定java源文件。相对路径是相对于当前目录。-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节点就是所有需设置注释的元素。
 
  
参考资料：
 
  
 
   
javadoc 应用详解