JDK 命令之 javadoc -- 生成API文档

命令简介

javadoc 是 Sun 公司提供的一个技术，JDK 的 bin 目录下你可以看到命令执行文件 javadoc，它从程序源代码中抽取注释内容，形成一个和源代码配套的 API 帮助文档。也就是说，只要在编写程序时以一套特定的标签作注释，在程序编写完成后，通过 Javadoc 就可以同时形成程序的开发文档了。

javadoc 命令只能提取源代码文件中的文档注释标记 /**...*/ 内的内容。文档注释内可以包含普通文本，HTML 标记和 JavaDoc 标记，这些内容构成 JavaDoc 文档。

在实现时，javadoc 依赖于 java 编译器完成其工作。javadoc 会调用 javac 编译类、方法、变量的声明部分，而忽略它们的实现部分。javadoc 会建立类的内容丰富的内部表示，包括类层次和“使用”关系，并读取源文件中文档注释的内容，解析注释中的注解，最后生成 HTML 格式的说明文档。

实际上，javadoc 将在不带方法体的纯 stub 文件的 .java 源文件上运行。这意味着可以创建 API 的最早期版本，在编写任何代码之前，就可编写文档注释并运行 javadoc。

依赖编译器可以确保 HTML 输出完全对应于实际实现，这些实现可能有赖于隐式的（而非显式的）源代码。例如，javadoc 将建立在 .class 文件中存在但在源代码中不存在的缺省构造方法（Java 语言规范的第 8.6.7 节）的文档。

当 javadoc 建立其内部文档结构时，它将加载所有引用的类。由于这一点，javadoc 必须能查找到所有引用的类，包括引导类、扩展类和用户类。有关详细信息，参见如何查找类。一般而言，所创建的类必须加载为扩展或位于 javadoc 的类路径中。

官方文档： JDK1.7 Linux 系统环境下 https://docs.oracle.com/javase/7/docs/technotes/tools/solaris/javadoc.html JDK1.7 Windows 系统环境下 https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html JDK1.8 Unix 系统环境下 https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javadoc.html JDK1.8 Windows 系统环境下 https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html

命令选项

查看命令使用说明：

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          利用位于  的程序包列表链接至位于  0 && containsText(str));
}

经常会使用 pre 标签来举例说明如何使用方法：

{@code
     Person[] men = people.stream()
                        .filter(p -> p.getGender() == MALE)
                        .toArray(Person[]::new);
}

注释示例代码

package priv.liaowenxiong.javaprac.javadoc;

/**
 * 这是一个汽车类
 * 
汽车类说明第一行
 * 汽车类说明第二行

 * See also {@link #measureAverageSpeed(double, int)} 
 * See also {@link #maxSpeed} 
 * See also {@link Person} 
 * See also {@link Person#eat()} 
 * See also {@link Person#sing(String)} 
 * @author liaowenxiong张学友
 * @version 1.0
 * @see #averageSpeed
 * @see Person
 * @see Person#eat()
 */
public class Bus {
    /**
     * 用来表示汽车行驶过程中的最大车速
     *
     * @author liaowenxiong
     * @see #averageSpeed
     */
    public double maxSpeed;
    /**
     * 用来表示汽车行驶过程中的平均车速
     */
    public double averageSpeed;
    /**
     * 用来表示汽车行驶过程中的水温
     */
    public float waterTemperature;
    /**
     * 用来表示天气的温度
     */
    public float temperature;

    public Bus() {
    }

    /**
     * @param distance 行驶路程，单位公里（km）
     * @param time     行驶时间，单位小时（h）
     * @return double类型 速度（km/h）
     * @author liaowenxiong123
     */
    public double measureAverageSpeed(double distance, int time) {
        double averageSpeed = distance / time;
        return averageSpeed;
    }
    
     /**
     * @return double类型 速度（km/h）
     * @author liaowenxiong123
     */
    public double measureMaxSpeed() {
        return 0;
    }
}

示例二：

package org.springframework.util;

/**
 * Miscellaneous {@link String} utility methods.
 *
 * 
Mainly for internal use within the framework; consider
 * Apache's Commons Lang
 * for a more comprehensive suite of {@code String} utilities.
 *
 * 
This class delivers some simple functionality that should really be
 * provided by the core Java {@link String} and {@link StringBuilder}
 * classes. It also provides easy-to-use methods to convert between
 * delimited strings, such as CSV strings, and collections and arrays.
 *
 * @author Rod Johnson
 * @author Juergen Hoeller
 * @author Keith Donald
 * @author Rob Harrop
 * @author Rick Evans
 * @author Arjen Poutsma
 * @author Sam Brannen
 * @author Brian Clozel
 * @since 16 April 2001
 */
public abstract class StringUtils {

	/**
	 * Decode the given encoded URI component value. Based on the following rules:
	 * 

	 * 
Alphanumeric characters {@code "a"} through {@code "z"}, {@code "A"} through {@code "Z"},
	 * and {@code "0"} through {@code "9"} stay the same.
	 * 
Special characters {@code "-"}, {@code "_"}, {@code "."}, and {@code "*"} stay the same.
	 * 
A sequence "{@code %xy}" is interpreted as a hexadecimal representation of the character.
	 * 
	 * 
	 * @param source the encoded String
	 * @param charset the character set
	 * @return the decoded value
	 * @throws IllegalArgumentException when the given source contains invalid encoded sequences
	 * @since 5.0
	 * @see java.net.URLDecoder#decode(String, String)
	 */
	public static String uriDecode(String source, Charset charset) {}

示例三：

package com.example.demo;

/**
 * 类 {@code OrderService} 订单服务层.
 *
 * 
 主要包括 创建订单、取消订单、查询订单等功能更
 *
 * @see Order
 * @author Mengday Zhang
 * @since 2018/5/12
 */
public class OrderService {

	/** 默认数量 {@value} */
    private static final Integer QUANTITY = 1;

    /**
     * 创建订单.
     *
     * 
 创建订单需要传用户id和商品列表(商品id和商品数量).
     *
     * 
{@code
     *  演示如何使用该方法
     *  List items = new ArrayList();
     *  Goods goods = new Goods(1L, BigDecimal.ONE);
     *  Goods goods2 = new Goods(2L, BigDecimal.TEN);
     *  items.add(goods);
     *  items.add(goods2);
     *
     *  Order order1 = new Order();
     *  order.setUserId("1");
     *  order.setItems(items);
     *  OrderService#createOrder(order);
     * }
     * 
     *
     * @param order 订单信息
     * @throws NullPointerException 参数信息为空
     * @exception IllegalArgumentException  数量不合法
     * @return 是否创建成功
     * @version 1.0
     * @see Order
     */
    public boolean createOrder(Order order) throws IllegalArgumentException{
        Objects.requireNonNull(order);

        List items = order.getItems();
        items.forEach(goods -> {
            BigDecimal quantity = goods.getQuantity();
            if (quantity == null || BigDecimal.ZERO.compareTo(quantity) == 0) {
                throw new IllegalArgumentException();
            }
        });

        System.out.println("create order...");

        return true;
    }
}

文档注解顺序

标记的顺序（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 标记
@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

文档注解

@xxx，这玩意叫法真多，有人说是标签，有人说是标记，有人说是标注，有人说是注解…

@version

指定版本信息，只能写一个，多写的也只会提取第一个 version。

@since

指定最早出现在哪个 JDK 版本：

package java.util.stream;

/**
* @since 1.8
*/
public interface Stream extends BaseStream {}

也可以跟是一个时间，表示文件当前创建的时间：

package org.springframework.util;

/**
* @since 16 April 2001
*/
public abstract class StringUtils {}

@author

指定作者，可以指定多个作者

@author liaowenxiong
@author zhangxueyou

上述这样写，生成的文档中作者名称之间是以逗号隔开的，想分行显示作者，可以写成：

@author liaowenxiongzhangxueyou

更多范例：

// 作者名称
@author Rod Johnson

// 作者、邮箱
@author Igor Hersht, igorh@ca.ibm.com

// 作者名称，带超链接邮箱地址
@author Ovidiu Predescu

// 邮件
@author shane_curcuru@us.ibm.com

// 组织名称
@author Apache Software Foundation

// 组织名称，带组织网址超链接
@author  Apache Jakarta Turbine

@see

生成参考其它 javaDoc 文档的链接，跳至其它 javaDoc 文档或文档中的某个部位。

语法有以下几种：

1.@see 类名 [链接名称] 会生成一个链接，点击链接会跳至指定类的首页。 例如：

/**
* @see priv.liaowenxiong.javaprac.javadoc.Bus 汽车类
* @see Person
* /

1.1类名 如果这个类在当前类有导入，即 import 语句包含这个类，或者在当前类同一个包下，那么可以只写类名，如果没有则要写全路径类名，

1.2链接名称 可以指定链接名称，上面例子中，“汽车类”就是链接名称，生成对应链接时名称就显示“汽车类”，不写链接名称，默认显示 priv.liaowenxiong.javaprac.javadoc.Bus。

2.@see #变量名 [链接名称] 生成一个链接，点击此链接跳至指定变量处。 没有指定类名，默认是当前类，会跳至本类指定的变量处。 变量只要写变量名即可，例如：

/**
* @see name
* /

2.1链接名称 同样可以指定链接名称，例如：@see name 姓名，链接名称就会显示“姓名”，不写链接名称就直接显示 name。

3.@see #方法 [链接名称] 生成一个链接，点击此链接会跳至指定的方法处。 没有指定类名，默认是当前类，会跳至本类指定的方法处。 例如：

/**
* @see add(int, int)
* /

3.1方法签名 方法需要写方法名和参数类型列表，没有参数也要写小括号，例如：@see show()。

4.@see 类名#方法名 [链接名称] 生成一个链接，点击此链接会跳至指定的其它类的指定方法处。

示例一：

/**
* @see Person#add(int, int)
* /

示例二：

/**
* @see java.net.URLDecoder#decode(String, String)
*/
public static String uriDecode(String source, Charset charset){}

4.1类名 如果这个类在当前类有导入，则直接写类名即可，如果没有则要写全路径类名。

5.@see 类名#变量名 [链接名称] 生成一个链接，点击此链接会跳至指定的其它类的指定变量处。 例如：

/**
* 
* @see Person#skinColor
* /

5.1类名 如果这个类在当前类有导入，则直接写类名即可，如果没有则要写全路径类名。

6.可以指定包名

/**
* @see java.util.stream
*/

7.可以指定纯文本，不含链接

/**
* @see "Person"
*/

如上加上双引号，只会在 See also【另请参阅】下显示文字 Person，无法点击跳转。

@linkplain

语法：{@linkplain package.class#member label} 作用：与{@link}相同，除了链接的标签以纯文本显示，而不是以代码字体显示，当标签是纯文本时很有用。

@link

生成内联链接，它和 @see 标记的区别在于 @link 标记能够嵌入到注释语句中，其在使用的地方产生超链接，而不是在"See Also"列表中生成。

/**
* Use the {@link #getComponentAt(int, int) getComponentAt} method.
* /
* 

Javadoc 会将其转换为如下代码：

Use the getComponentAt method.

另外 @link 和 {@linkplain} 类似，只是 @link 是代码字体格式，而 {@linkplain} 是纯文本字体格式。

1.跳至当前类中的指定方法 语法格式： {@link #方法名(参数类型) [链接名称]}

例如：

/**
 * See also {@link #measureAverageSpeed(double, int) measureAverageSpeed} 
 */

1.1链接名称 链接名称可以省略，那么链接名称就显示方法名和参数

2.跳至当前类中的指定变量处 语法格式： {@link #变量名 [链接名称]}

例如：

/**
* See also {@link #maxSpeed}
* /

2.1链接名称 可以指定链接名称，不指定则显示变量名

3.跳至指定的其它类首页 语法格式： {@link 类名 [链接名称]}

例如：

/**
 * See also {@link priv.liaowenxiong.javaprac.javadoc.Person}
 */

3.1类名 如果在当前类的同一个包下或者当前类有导入此类，则直接写类名即可，否则需要写全路径类名

3.2链接名称 可以指定自定义的链接名称，不指定则显示类名

4.跳至指定的其它类的指定变量处 语法格式： {@link 类名#变量名 [链接名称]}

例如：

/**
 * See also {@link Person#skinColor 肤色}
 */

4.1类名 如果在当前类的同一个包下或者当前类有导入此类，则直接写类名即可，否则需要写全路径类名

4.2链接名称 可以指定自定义的链接名称，不指定则显示“类名.变量名”

5.跳至指定的其它类的指定方法处

语法格式： {@link 类名#方法名(参数类型) [链接名称]}

例如：

/**
 * See also {@link Person#eat() eat()}
 * See also {@link Person#sing(String)}
 */

5.1类名 如果在当前类的同一个包下或者当前类有导入此类，则直接写类名即可，否则需要写全路径类名

5.2链接名称 可以指定自定义的链接名称，如果不指定则会显示“类名.方法签名”，例如：Person.sing(String)

@deprecated

用来标明被标记的类，变量或方法已过时，不提倡使用（类名/方法名上会有一个划去的横杠）。

语法： @deprecated deprecated-text

针对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)
 */

@param

语法：@param parameter-name description 作用：对方法中的参数进行说明，我们应该针对方法的每一个参数都使用一个该标记。

描述方法的参数，必须要有文字描述，否则生成文档时会提示“警告: @param 没有说明”

示例：

/**
* @param str the {@code CharSequence} to check (may be {@code null})
*/
public static boolean containsWhitespace(@Nullable CharSequence str) {}

一般类中支持泛型时会通过 @param 来解释泛型的类型：

/**
* @param  the type of elements in this list
*/
public interface List extends Collection {}

@return

语法：@return description

描述方法的返回值，如果没有返回值，不要加上这个注解，生成文档时会提示“错误: @return 的用法无效”

示例：

/**
* @return {@code true} if the {@code String} is not {@code null}, its
*/
public static boolean hasText(@Nullable String str){}

@throws

语法： @throws class-name description

指明方法可能抛出的异常，必须文字描述抛出异常的原因，否则生成文档时会提示“ 警告: @throws 没有说明”。 如果会抛出多个异常，需要写多个此注解。

示例一：

/**
* @throws ArrayIndexOutOfBoundsException 可能抛出数组索引越界异常
* @author liaowenxiong123
*/

示例二：

/**
* @throws IllegalArgumentException when the given source contains invalid encoded sequences
*/
public static String uriDecode(String source, Charset charset){}

@exception

这个注解已经被 @throws 取代了，同样表示可能抛出的异常，不论是编译时异常还是运行时异常

/**
* @exception IllegalArgumentException if key is null.
*/
public static Object get(String key) throws IllegalArgumentException {}

@value

用于标注在常量上，{@value} 用于表示常量的值

语法格式： {@value package.class#field}

当在常量字段的注释中使用 {@value} 时(没有任何参数)，它将显示该常量的值：

/**
 * The value of this constant is {@value}.
 */
public static final String SCRIPT_START = "script";

/** 默认数量 {@value} */
private static final Integer QUANTITY = 1;

当在任何 doc 注释中与参数 package.class#field 字段一起使用时，它将显示指定常量的值：

/**
 * Evaluates the script starting with {@value #SCRIPT_START}.
 */
public String evalScript(String script) {
}

@code

声明其中的内容是代码注释。 将文本标记为代码样式的文本，在 code 标签内部可以使用 等不会被解释成 html 标签，code 标签有自己的样式，但是样式效果不明显。所以使用的时候，必须借助 html 标签

，否则样式是无法保留的。
 
语法格式： {@code text}
 
生成文档时，{@code text} 会被解析成  text 
 
使用方式： 
{@code代码}
 
@docRoot 
代表生成文档的根目录。
 
语法格式： {@docRoot}
 
例如，在注释中的用法如下：
 
/**
* See the Copyright.
*/
 
另请参阅： {@docRoot}
 
@inheritDoc 
语法格式： {@inheritDoc}
 
@inheritDoc 用于注解在重写方法或者子类上，用于继承父类中的Javadoc。 基类的文档注释被继承到了子类，子类可以再加入自己的注释（特殊化扩展）。 @return @param @throws 也会被继承。
 
@literal 
显示文本，而不将文本解析为HTML标记或嵌套的Javadoc标记。
 
语法： {@literal text}
 
例如：
 
/**
*
* {@literal A
C}
* /
 
上面的文本 AC 会原样显示出来，而不会把 
 解释为段落标记。
 
@serial 
用于默认可序列化字段的doc注释中。
 
语法格式： @serial field-description | include | exclude
 
field-description 应该解释字段的含义并列出可接受的值。
 
include和exclude参数标识是否应将 类 或 包 包括在序列化窗体页中或将其排除在序列化窗体页之外。如下：
 
public 或 protected 类继承了Serializable 则是 included ，除非类(或者包) 标记为 @serial exclude.
 
private 或 package-private 类继承了Serializable 则是excluded，除非类(或者包) 标记为@serial include.
 
注意：类级别的@serial标记覆盖包级别的@serial标记。
 
@serialData 
语法：@serialField field-name field-type field-description