(JDK)[创建和构建应用程序的主要工具] 之 javadoc

该的Javadoc ™工具解析声明和文档注释一组 Java 源文件并生成对应的一组描述（默认）的HTML页面的公有和受保护类，嵌套类（但不是匿名内部类），接口，构造，方法和领域。您可以使用它来生成API（应用程序编程接口）文档或一组源文件的实现文档。 您可以在整个包，单个源文件或两者上运行Javadoc工具。记录整个包时，您可以使用-subpackages 从顶级目录递归遍历，或者传递明确的包名列表。记录单个源文件时，会传入source（.java）文件名列表。示例在本文档的末尾给出。接下来介绍Javadoc如何处理源文件。

2. 命令用法

用法: 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> 的程序包列表链接至位于 <url> 的文档
  -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>              指定输出的字符编码
复制代码

eg:

javadoc -encoding UTF-8 -charset UTF-8 TestJavaDoc.java

正在加载源文件TestJavaDoc.java...
正在构造 Javadoc 信息...
标准 Doclet 版本 1.8.0_161
正在构建所有程序包和类的树...
正在生成./TestJavaDoc.html...
正在生成./package-frame.html...
正在生成./package-summary.html...
正在生成./package-tree.html...
正在生成./constant-values.html...
正在构建所有程序包和类的索引...
正在生成./overview-tree.html...
正在生成./index-all.html...
正在生成./deprecated-list.html...
正在构建所有类的索引...
正在生成./allclasses-frame.html...
正在生成./allclasses-noframe.html...
正在生成./index.html...
正在生成./help-doc.html...
复制代码

3. 主要标记简介

3.1 @see

参考。 添加“另请参见”标题，其中包含指向引用的链接/文本条目/参考类。文档注释可以包含任意数量的 @see标记，这些标记都分组在同一标题下。此标记在任何文档注释中都有效：概述，包，类，接口，构造函数，方法或字段。要将句子中的内嵌链接插入包，类或成员，请参阅{@link}。以下是@see三种最常见的使用

3.1.1 @see "字符串"

添加字符串的文本条目。没有生成链接。该字符串是书籍或其他对URL不可用的信息的引用。Javadoc工具通过查找double-quote（"）作为第一个字符来区别于以前的情况。eg：

@see“Java编程语言”
复制代码

3.1.2 @see <a href="URL＃值">标签 </a>

加URL＃value定义的链接。该 URL＃值是相对或绝对URL。Javadoc工具通过查找小于号（<）作为第一个字符来区别于其他情况。eg：

@see <a href="https//blog.catalpaflat.cn/"> CatalpaFlat </a>
复制代码

3.1.3 @see package.class #成员 标签

用于标明参考某个类或某个类的成员（字段/方法/构造函数等）

eg：

引用当前类
@see  #字段
@see  #方法（Type，Type，...）
@see  #方法的成员（类型argname，类型argname，...）
@see  #构造函数（Type，Type，...）
@see  #构造函数（类型argname，类型argname，.. 。）

引用当前或导入的包中的另一个类
@see  Class #字段
@see  Class #方法（Type，Type，...）
@see  类#方法（类型argname，Type argname，...）
@see  类#构造函数（Type，Type，...）
@see  类#构造函数（类型argname，类型argname，...）
@see  Class.NestedClass 
@see  类

引用另一个包中的元素（完全限定）
@see  package.Class #字段
@see  package.Class #方法（Type，Type，...）
@see  package.Class #方法（类型argname，类型argname，...）
@see  package.Class #构造函数（Type，Type，...）
@see  package.Class #构造函数（类型argname，Type argname，...）
@see  package.Class.NestedClass 
@see  package.Class
@see  package
复制代码

3.2 @author

使用-author选项时，将“Author”条目与指定的name-text一起添加到生成的文档中。文档注释可能包含多个@author标记。您可以为每个@author标记指定一个名称或为每个标记指定多个名称 在前一种情况下，Javadoc工具,在名称之间插入逗号（）和空格。在后一种情况下，只需将整个文本复制到生成的文档而不进行解析。因此，如果需要除逗号之外的本地化名称分隔符，则可以每行使用多个名称。

eg:

@author CatalpaFlat
复制代码

3.3 @version

@version标记的参数的Java软件约定是SCCS字符串“％I％，％G％”，1.39, 02/28/97当从SCCS中检出文件时，它转换为类似“ ”（mm / dd / yy）的内容。

文档注释可能包含多个@version标记。如果有意义，您可以为每个@version标记指定一个版本号，或为每个标记指定 多个版本号。在前一种情况下，Javadoc工具,在名称之间插入逗号（）和空格。在后一种情况下，只需将整个文本复制到生成的文档而不进行解析。因此，如果需要除逗号之外的本地化名称分隔符，则可以每行使用多个名称。

eg:

@version 1.0.0, 13 Dec 2014
复制代码

3.4 {@link}

• 格式：{@link package.class #成员 标签}
• 插入内容：插入带有可见文本标签的内嵌链接，该链接指向引用类的指定包、类或成员名称的文档。
• 此标记在所有文档注释中都有效：概述，包，类，接口，构造函数，方法和字段，包括任何标记的文本部分（eg: @return，@ param和@deprecated）。
• 和@see的区别：两者都需要相同的引用，并且接受{package.class #成员 和标签}完全相同的语法。主要区别在于 {@link}生成内联链接而不是将链接放在“另请参见”部分。此外，{@link} 标记以花括号开头和结尾，以将其与内嵌文本的其余部分分开。如果您需要在标签内使用“}”，请使用HTML实体表示法＆＃125;
• {@link}句子中允许的标签数量没有限制。您可以在任何文档注释的主要描述部分或任何标记的文本部分（eg: @deprecated，@return或@param）中使用此标记。

eg:

// 引用getComponentAt(int, int)该方法的注释
Use the {@link #getComponentAt(int, int) getComponentAt} method.
复制代码

3.5 {@value}

3.5.1 在{@value}静态字段的doc注释中使用（无任何参数）时，它显示该常量的值：

/**
 * The value of this constant is {@value}.
 */
public static final String SCRIPT_START = "<script>"
复制代码

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

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

复制代码

3.6 @param

参数名称 描述。

将具有指定参数名称的参数 后跟指定描述添加到“参数”部分。在编写文档注释时，可以将描述继续到多行。此标记仅在方法，构造函数或类的doc注释中有效。 参数名称可以是方法或构造函数中的参数名称，也可以是类，方法或构造函数的类型参数的名称。在此参数名称周围使用尖括号指定使用类型参数。

eg:

//类范型
 /**
  * @param <E> Type of element stored in a list
  */
 public interface List<E> extends Collection<E> {
 }


//方法上
/**
  * @param string  the string to be converted
  * @param type    the type to convert the string to
  * @param <T>     the type of the element
  * @param <V>     the value of the element
  */
 <T, V extends T> V convert(String string, Class<T> type) {
 }
复制代码

3.7 @return

添加带有描述文本的“返回”部分。该文本应描述返回类型和允许的值范围。此标记仅在方法的doc注释中有效。 有关更多详细信息，请参阅 编写@return标记。

eg:

/**
 *
 * @return String
 */
private String obtain(){
    return "CatalpaFlat";
}
复制代码

3.8 @throws、@exception

在@throws和@exception标签是同义词。使用类名和 描述文本向生成的文档添加“throw”子标题。类名是可通过该方法抛出的异常的名称。此标记仅在方法或构造函数的doc注释中有效。如果未完全指定此类，则Javadoc工具使用搜索顺序查找此类。@throws对于相同或不同的例外，可以在给定的doc注释中使用多个 标签。

为了确保记录所有已检查的异常，如果 @throwsthrows子句中的异常不存在标记，则Javadoc工具会自动将该异常添加到HTML输出（没有描述），就像使用@throws标记记录一样。

@throws仅当在重写方法中显式声明异常时，才会将文档从重写方法复制到子类。从接口方法复制到实现方法也是如此。您可以使用{@inheritDoc}强制@throws继承文档。

3.9 {@inheritDoc}

将文档从“copies”可继承类或可实现的接口继承（复制）到此标记位置的当前doc注释中。这允许您在继承树的更高位置编写更多通用注释，并在复制的文本周围编写。 此标记仅在文档注释中的这些位置有效：

• 在方法的主要描述块中。在这种情况下，主要描述从层次结构中的类或接口复制。
• 在方法的@return，@ param和@throws标签的文本参数中。在这种情况下，标记文本将从层次结构中的相应标记复制。

有关如何在继承层次结构中找到注释的更准确说明，请参见自动复制方法注释。请注意，如果缺少此标记，则根据该部分中描述的规则自动继承注释。

4. 各文档注释

4.1 包文档标签

描述：包标签是可以出现在包的文档注释中的标签（位于名为package.htmlor 的源文件中 package-info.java）。该 @serial标签只能用这里使用 include或exclude说法。

可用标签 ️：

结构：

1. 该包的简要功能描述
2. 该包的详细描述（@link /@code）
3. 新建该包时当前项目的版本 @since
4. 作者 @author
5. 参考现有类 @see

eg：

/**
 * Provides the classes necessary to create an  
 * applet and the classes an applet uses 
 * to communicate with its applet context.
 * <p>
 * The applet framework involves two entities:
 * the applet and the applet context.
 * An applet is an embeddable window (see the
 * {@link java.awt.Panel} class) with a few extra
 * methods that the applet context can use to 
 * initialize, start, and stop the applet.
 *
 * @since 1.0
 * @see java.awt
 */
package java.lang.applet;
复制代码

4.2 类和接口文档标记

可用标签 ️：

结构：

1. 该类的简要功能描述
2. 该类的详细描述
3. 作者 @author
4. 撰写该类时类版本 @version
5. 撰写该类时当前项目的版本 @since
6. 参考现有类 @see

eg:

/**
 * A class representing a window on the screen.
 * For example:
 * <pre>
 *    Window win = new Window(parent);
 *    win.show();
 * </pre>
 *
 * @author  CatalpaFlat
 * @version 1.15, 13 Dec 2006
 * @see     java.awt.BaseWindow
 * @see     java.awt.Button
 */
class Window extends BaseWindow {
   ...
}
复制代码

4.3 字段文档标签

可用标签 ️：

结构：

1. 描述 {@link} / {@linkplain}
2. @serial/ @serialField
3. {@value}
4. {@docRoot}
5. @see

eg:

/**
 * The X-coordinate of the component.
 *
 * @see #getLocation()
 */
int x = 1263732;
复制代码

4.4 构造函数和方法文档标记

除了 @return它们不能出现在构造函数中，并且 {@inheritDoc}具有某些限制。该@serialData标签只能用于文档注释中使用某些序列化方法。

可用标签 ️：

eg:

/**
 * Returns the character at the specified index. An index
 * ranges from <code>0</code> to <code>length() - 1</code>.
 *
 * @param     index  the index of the desired character.
 * @return    the desired character.
 * @exception StringIndexOutOfRangeException
 *              if the index is not in the range <code>0</code>
 *              to <code>length()-1</code>.
 * @see       java.lang.Character#charValue()
 */
public char charAt(int index) {
   ...
}
复制代码

5. 示例

/**
 * Represents an HTTP request or response entity, consisting of headers and body.
 *
 * <p>Typically used in combination with the {@link org.springframework.web.client.RestTemplate},
 * like so:
 * <pre class="code">
 * HttpHeaders headers = new HttpHeaders();
 * headers.setContentType(MediaType.TEXT_PLAIN);
 * HttpEntity<String> entity = new HttpEntity<String>(helloWorld, headers);
 * URI location = template.postForLocation("http://example.com", entity);
 * </pre>
 * or
 * <pre class="code">
 * HttpEntity<String> entity = template.getForEntity("http://example.com", String.class);
 * String body = entity.getBody();
 * MediaType contentType = entity.getHeaders().getContentType();
 * </pre>
 * Can also be used in Spring MVC, as a return value from a @Controller method:
 * <pre class="code">
 *  RequestMapping("/handle")
 * public HttpEntity<String> handle() {
 *   HttpHeaders responseHeaders = new HttpHeaders();
 *   responseHeaders.set("MyResponseHeader", "MyValue");
 *   return new HttpEntity<String>("Hello World", responseHeaders);
 * }
 * </pre>
 *
 * @author Arjen Poutsma
 * @author Juergen Hoeller
 * @since 3.0.2
 * @see org.springframework.web.client.RestTemplate
 * @see #getBody()
 * @see #getHeaders()
 */
public class HttpEntity<T> {

	/**
	 * The empty {@code HttpEntity}, with no body or headers.
	 */
	public static final HttpEntity<?> EMPTY = new HttpEntity<>();
	
	/**
	 * Create a new, empty {@code HttpEntity}.
	 */
	protected HttpEntity() {
		this(null, null);
	}
	
	/**
	 * Create a new {@code HttpEntity} with the given headers and no body.
	 * @param headers the entity headers
	 */
	public HttpEntity(MultiValueMap<String, String> headers) {
		this(null, headers);
	}
	/**
	 * Returns the body of this entity.
	 */
	@Nullable
	public T getBody() {
		return this.body;
	}

	/**
	 * Indicates whether this entity has a body.
	 */
	public boolean hasBody() {
		return (this.body != null);
	}


	@Override
	public boolean equals(@Nullable Object other) {
		if (this == other) {
			return true;
		}
		if (other == null || other.getClass() != getClass()) {
			return false;
		}
		HttpEntity<?> otherEntity = (HttpEntity<?>) other;
		return (ObjectUtils.nullSafeEquals(this.headers, otherEntity.headers) &&
				ObjectUtils.nullSafeEquals(this.body, otherEntity.body));
	}
}
复制代码