Java教程

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

本文主要是介绍JDK 命令之 javadoc -- 生成API文档，对大家解决编程问题具有一定的参考价值，需要的程序猿们随着小编来一起学习吧！

文章目录

  • 命令简介
  • 命令选项
  • 中文乱码
  • javadoc 命令实例
    • 进入源代码文件所在目录，解析指定的源代码文件，生成 API 文档
    • 解析指定包下的所有源码文件，生成 API 文档
    • 指定源文件根目录，再指定具体的包路径，解析其中的源码文件，生成 API 文档
    • 指定多个源文件根目录，再指定多个包路径，解析其中的源码文件，生成 API 文档
    • 解析具体路径所指定的源代码文件，生成 API 文档
    • 指定源文件的根目录，再指定包路径，递归遍历所有的子包，解析其中的源文件，生成 API 文档
  • 文档注释格式规范
    • 简要概述
      • 关于类/接口的概要描述
      • 关于方法的概要描述
    • 详细描述
      • 关于类的详细描述
      • 关于方法的详细描述
  • 注释中的 HTML 标签
  • 注释示例代码
  • 文档注解顺序
  • 可多次使用的注解
  • 文档注解
    • @version
    • @since
    • @author
    • @see
    • @linkplain
    • @link
    • @deprecated
    • @param
    • @return
    • @throws
    • @exception
    • @value
    • @code
    • @docRoot
    • @inheritDoc
    • @literal
    • @serial
    • @serialData
  • 其它注解

命令简介

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

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

JDK 的 bin 目录下你可以看到命令执行文件 javadoc，javadoc 命令会从源文件中读取文档注释中的内容，并识别注释中的注解，最后生成 HTML 格式的类说明文档。

官方文档：
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 <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>              指定输出的字符编码

命令的语法格式：
javadoc [option] [packagenames] [sourcefiles]

选项说明
-public仅为public访问级别的类及类的成员生成javaDoc文档
-proteceted这是默认选项，仅为public和protected访问级别的类及类的成员生成javadoc文档，不包含私有和默认访问级别的类和相关的成员
-package仅为public,protected和默认访问级别的类及类的成员生成javaDoc文档，不包含私有访问级别的类和相关的成员
-private为public,protected,默认和private访问级别的类及类的成员生成javadoc文档
-version解析@version标记
-author解析@author标记
-splitindex将索引分为每个字母对应一个索引文件，似乎这样的索引文件，查询体验会更好
-sourcepath 指定源文件的路径，试过无效，不知道怎么使用？？
-classpath 指定classpath
-d 指定javaDoc文档的输出目录

中文乱码

生成的文档中如果中文无法正常显示可以尝试在命令中使用以下选项：

设置源码编码方式：-encoding UTF-8
指定输出的字符编码：-charset UTF-8
要使用的语言环境：-locale zh_CN

javadoc 命令实例

进入源代码文件所在目录，解析指定的源代码文件，生成 API 文档

例如，你先进入 Bus.java 的所在目录后，再执行下面的命令语句：

javadoc -d /Users/liaowenxiong/desktop/api -author -version Bus.java

这条命令编译一个名为 Bus.java 的 Java 源文件，并将生成的文档存放在目录 /Users/liaowenxiong/desktop/api，指定了选项 author 表示会提取类注释中的作者姓名，但是不会提取方法注释中的作者姓名；选项 version 表示会提取版本的信息 。

在这里插入图片描述

解析指定包下的所有源码文件，生成 API 文档

你要先进入 Source Root 目录下，一般是指 src 目录下，然后再执行下方的命令语句：

javadoc -d /Users/liaowenxiong/desktop/test/api -version -author priv.liaowenxiong.javaprac.javadoc

注：子包的源码文件不会被解析

指定源文件根目录，再指定具体的包路径，解析其中的源码文件，生成 API 文档

以下这种方式，你无需进入 Source Root 目录下：

javadoc -d /Users/liaowenxiong/desktop/test/api -sourcepath /Users/liaowenxiong/documents/IdeaProjects/java-practise/javadoc/src priv.lwx.javaprac.javadoc

上述的命令语句，你可以运行在任意目录下。因为通过 -sourcepath 指明了顶层包的位置，以及要生成的文档的包。
注：子包的源码文件不会被解析

指定多个源文件根目录，再指定多个包路径，解析其中的源码文件，生成 API 文档

你还可以指定多个源文件的根目录：

javadoc -d /Users/liaowenxiong/desktop/test/api -sourcepath /Users/liaowenxiong/documents/IdeaProjects/java-practise/javadoc/src:/Users/liaowenxiong/documents/IdeaProjects/java-practise/interface/src priv.lwx.javaprac.javadoc priv.lwx.javaprac.inter

注：
1.多个目录之间使用冒号分隔，Windows 系统下则使用分号分隔；包路径之间使用空格分隔。
2.子包的源码文件不会被解析

解析具体路径所指定的源代码文件，生成 API 文档

例如，进入到项目根目录下后，以相对路径指定两个源码文件，解析生成 API 文档，命令语句如下：

liaowenongdeair:java-practise liaowenxiong$ javadoc -d /Users/liaowenxiong/desktop/test/api -version -author javadoc/src/priv/liaowenxiong/javaprac/javadoc/Bus.java javadoc/src/priv/liaowenxiong/javaprac/javadoc/Person.java

注意，无法直接指定目录路径，提示：

liaowenongdeair:java-practise liaowenxiong$ javadoc -d /Users/liaowenxiong/desktop/test/api -version -author javadoc/src/priv/liaowenxiong/javaprac/javadoc
javadoc: 错误 - 非法的程序包名称: "javadoc/src/priv/liaowenxiong/javaprac/javadoc"

指定源文件的根目录，再指定包路径，递归遍历所有的子包，解析其中的源文件，生成 API 文档

使用 -subpackages 指定包，javadoc 会递归遍历其中所有的子包：

javadoc -d /Users/liaowenxiong/desktop/test/api -sourcepath /Users/liaowenxiong/documents/IdeaProjects/java-practise/javadoc/src -subpackages priv -exclude priv.liaowenxiong.javaprac.javadoc.test:priv.liaowenxiong.javaprac.javadoc.demo

javadoc -d /Users/liaowenxiong/desktop/test/api -sourcepath /Users/liaowenxiong/documents/IdeaProjects/java-practise/javadoc/src -subpackages priv

注：
1./Users/liaowenxiong/documents/IdeaProjects/java-practise/javadoc/src 这一串就是 Source Root 。
2.priv 这是 Source Root 下的顶级包
3.-exclude ，指定要排除的程序包列表，多个包直接使用冒号 : 分割
4.如果想要对其它包树也进行遍历，则只需要在 -subpackages 的参数上附加上即可，例如：priv:javax:org.xml.sax

文档注释格式规范

一般分为三段：

第一段：概要描述，通常用一句或者一段话简要描述该类的作用，以英文句号作为结束
第二段：详细描述，通常用一段或者多段话来详细描述该类的作用，一般每段话都以英文句号作为结束
第三段：文档注解，如果是类注释，则标注作者、版本、创建时间、参阅类等信息；如果是方法，则标注作者、参数、返回值、异常、参阅等信息

注：注释文本中的第一个英文句点 . 之前的描述文本默认是简述部分的内容，一个英文句点之后的文本内容则会出现在详细描述部分。

示例如下：

/**
 *  Person类的简述
 *  <p>Person类的详细说明第一行<br>
 *  Person类的详细说明第二行
 * @author liaowenxiong
 * @see Bus
 */

注：凡涉及到类名和方法名都用 @code 标记，凡涉及到组织的，一般用 <a> 标签指明官方网址。

简要概述

关于类/接口的概要描述

单行示例：

package org.springframework.util;
/**
 * Miscellaneous {@link String} utility methods.
 * 
 */
public abstract class StringUtils {

多行示例：

package java.lang;

/**
 * Class {@code Object} is the root of the class hierarchy.
 * Every class has {@code Object} as a superclass. All objects,
 * including arrays, implement the methods of this class.
 */
public class Object {}

关于方法的概要描述

详细描述

关于类的详细描述

详细描述一般用一段或者几个段落来详细描述类的作用，详细描述中可以使用 html 标签，如 <p>、<pre>、<a>、<ul>、<i> 等标签， 通常详细描述都以段落 <p> 标签开始。

详细描述和概要描述中间通常有一个空行来分割。

package org.springframework.util;

/**
 * Miscellaneous {@link String} utility methods.
 *
 * <p>Mainly for internal use within the framework; consider
 * <a href="http://commons.apache.org/proper/commons-lang/">Apache's Commons Lang</a>
 * for a more comprehensive suite of {@code String} utilities.
 *
 * <p>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.
 *
 */
public abstract class StringUtils {

关于方法的详细描述

注释中的 HTML 标签

方法详细描述上经常使用 html 标签来，通常都以 p 标签开始，而且 p 标签通常都是单标签，不使用结束标签，其中使用最多的就是 p 标签和 pre 标签，ul 标签，i 标签。

pre 标签可定义预格式化的文本。被包围在 pre 标签中的文本通常会保留空格和换行符。而文本也会呈现为等宽字体，pre 标签的一个常见应用就是用来表示计算机的源代码。

一般 p 经常结合 pre 使用，或者 pre 结合 @code 共同使用。

注意：pre 标签中如果有小于号、大于号，例如泛型，在生成 javadoc 时会报错。

/**
 * Check whether the given {@code CharSequence} contains actual <em>text</em>.
 * <p>More specifically, this method returns {@code true} if the
 * {@code CharSequence} is not {@code null}, its length is greater than
 * 0, and it contains at least one non-whitespace character.
 * <p><pre class="code">
 * StringUtils.hasText(null) = false
 * StringUtils.hasText("") = false
 * StringUtils.hasText(" ") = false
 * StringUtils.hasText("12345") = true
 * StringUtils.hasText(" 12345 ") = true
 * </pre>
 * @param str the {@code CharSequence} to check (may be {@code null})
 * @return {@code true} if the {@code CharSequence} is not {@code null},
 * its length is greater than 0, and it does not contain whitespace only
 * @see Character#isWhitespace
 */
public static boolean hasText(@Nullable CharSequence str) {
	return (str != null && str.length() > 0 && containsText(str));
}

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

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

注释示例代码

package priv.liaowenxiong.javaprac.javadoc;

/**
 * 这是一个汽车类
 * <p>汽车类说明第一行<br>
 * 汽车类说明第二行<p>
 * See also {@link #measureAverageSpeed(double, int)} <br>
 * See also {@link #maxSpeed} <br>
 * See also {@link Person} <br>
 * See also {@link Person#eat()} <br>
 * See also {@link Person#sing(String)} <br>
 * @author liaowenxiong<br>张学友
 * @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.
 *
 * <p>Mainly for internal use within the framework; consider
 * <a href="http://commons.apache.org/proper/commons-lang/">Apache's Commons Lang</a>
 * for a more comprehensive suite of {@code String} utilities.
 *
 * <p>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:
	 * <ul>
	 * <li>Alphanumeric characters {@code "a"} through {@code "z"}, {@code "A"} through {@code "Z"},
	 * and {@code "0"} through {@code "9"} stay the same.</li>
	 * <li>Special characters {@code "-"}, {@code "_"}, {@code "."}, and {@code "*"} stay the same.</li>
	 * <li>A sequence "{@code %<i>xy</i>}" is interpreted as a hexadecimal representation of the character.</li>
	 * </ul>
	 * 
	 * @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} 订单服务层.
 *
 * <p> 主要包括 创建订单、取消订单、查询订单等功能更
 *
 * @see Order
 * @author <a href="mailto:mengday.zhang@gmail.com">Mengday Zhang</a>
 * @since 2018/5/12
 */
public class OrderService {

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

    /**
     * 创建订单.
     *
     * <p> 创建订单需要传用户id和商品列表(商品id和商品数量).
     *
     * <p><pre>{@code
     *  演示如何使用该方法
     *  List<Goods> 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);
     * }
     * </pre>
     *
     * @param order 订单信息
     * @throws NullPointerException 参数信息为空
     * @exception IllegalArgumentException  数量不合法
     * @return 是否创建成功
     * @version 1.0
     * @see Order
     */
    public boolean createOrder(Order order) throws IllegalArgumentException{
        Objects.requireNonNull(order);

        List<Goods> 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<T> extends BaseStream<T, Stream<T>> {}

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

package org.springframework.util;

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

@author

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

@author liaowenxiong
@author zhangxueyou

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

@author liaowenxiong<br>zhangxueyou

更多范例：

// 作者名称
@author Rod Johnson

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

// 作者名称，带超链接邮箱地址
@author <a href="mailto:ovidiu@cup.hp.com">Ovidiu Predescu</a>

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

// 组织名称
@author Apache Software Foundation

// 组织名称，带组织网址超链接
@author <a href="https://jakarta.apache.org/turbine"> Apache Jakarta Turbine</a>

@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 <a href="package-summary.html">java.util.stream</a>
*/

@linkplain

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

@link

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

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

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

Use the <a href="Component.html#getComponentAt(int, int)">getComponentAt</a> 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 <E> the type of elements in this list
*/
public interface List<E> extends Collection<E> {}

@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 <code>key</code> 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 标签 <pre>，否则样式是无法保留的。

语法格式：
{@code text}

生成文档时，{@code text} 会被解析成 <code> text </code>

使用方式：
<pre>{@code代码}</pre>

@docRoot

代表生成文档的根目录。

语法格式：
{@docRoot}

例如，在注释中的用法如下：

/**
* See the <a href="{@docRoot}/copyright.html">Copyright</a>.
*/

另请参阅：
{@docRoot}

@inheritDoc

语法格式：
{@inheritDoc}

@inheritDoc 用于注解在重写方法或者子类上，用于继承父类中的Javadoc。
基类的文档注释被继承到了子类，子类可以再加入自己的注释（特殊化扩展）。
@return @param @throws 也会被继承。

@literal

显示文本，而不将文本解析为HTML标记或嵌套的Javadoc标记。

语法：
{@literal text}

例如：

/**
*
* {@literal A<p>C}
* /

上面的文本 A<B>C 会原样显示出来，而不会把 <p> 解释为段落标记。

@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

其它注解

此外还有@serial、@serialField、@serialData、{@docRoot}、{@inheritDoc}、{@literal}、{@code} {@value arg}几个不常用的标签，由于不常使用，我们不展开叙述，感兴趣的读者可以查看帮助文档。

这篇关于JDK 命令之 javadoc -- 生成API文档的文章就介绍到这儿，希望我们推荐的文章对大家有所帮助，也希望大家多多支持为之网！
您可能喜欢
栏目导航