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

时间 2019-11-07

标签 jdk 建立构建应用程序主要工具 javadoc 栏目 Java 繁體版

原文原文链接

1. 简述

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

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:java

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三种最多见的使用node

3.1.1 @see "字符串"

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

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

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

加URL＃value定义的连接。该 URL＃值是相对或绝对URL。Javadoc工具经过查找小于号（<）做为第一个字符来区别于其余状况。eg：spring

@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工具,在名称之间插入逗号（）和空格。在后一种状况下，只需将整个文本复制到生成的文档而不进行解析。所以，若是须要除逗号以外的本地化名称分隔符，则能够每行使用多个名称。bash

eg:app

@author CatalpaFlat
复制代码

3.3 @version

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

文档注释可能包含多个@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说法。

可用标签🏷️：

包标签	描述
@see	参考
@since	since-text（用于当前项目版本）
@serial	描述
@author	做者
@version	版本
{@link}	入带有可见文本标签的内嵌连接，该连接指向引用类的指定包，类或成员名称的文档。
{@linkplain}	{@link}与连接标签相同，除了代码字体外，以纯文本显示。标签是纯文本时颇有用
{@docRoot}	表示从任何生成的页面生成的文档（目标）根目录的相对路径（版权标明）

结构：

该包的简要功能描述
该包的详细描述（@link /@code）
新建该包时当前项目的版本 @since
做者 @author
参考现有类 @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 类和接口文档标记

可用标签🏷️：

包标签	描述
@see	参考
@since	since-text（用于当前项目版本）
@serial	描述
@deprecated	设置过时
@author	做者
@version	版本
{@link}	入带有可见文本标签的内嵌连接，该连接指向引用类的指定包，类或成员名称的文档。
{@linkplain}	{@link}与连接标签相同，除了代码字体外，以纯文本显示。标签是纯文本时颇有用
{@docRoot}	表示从任何生成的页面生成的文档（目标）根目录的相对路径（版权标明）

结构：

该类的简要功能描述
该类的详细描述
做者 @author
撰写该类时类版本 @version
撰写该类时当前项目的版本 @since
参考现有类 @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 字段文档标签

可用标签🏷️：

包标签	描述
@see	参考
@since	since-text（用于当前项目版本）
@deprecated	设置过时
@serial	描述
@serialField	字段类型/字段描述
{@link}	入带有可见文本标签的内嵌连接，该连接指向引用类的指定包，类或成员名称的文档。
{@linkplain}	{@link}与连接标签相同，除了代码字体外，以纯文本显示。标签是纯文本时颇有用
{@docRoot}	表示从任何生成的页面生成的文档（目标）根目录的相对路径（版权标明）
{@value}	常量的值

结构：

描述 {@link} / {@linkplain}
@serial/ @serialField
{@value}
{@docRoot}
@see

eg:

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

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

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

可用标签🏷️：

包标签	描述
@see	参考
@since	since-text（用于当前项目版本）
@param	参数信息
@return	返回信息
@deprecated	设置过时
@throws 和 @exception	异常
@serialData
{@link}	入带有可见文本标签的内嵌连接，该连接指向引用类的指定包，类或成员名称的文档。
{@linkplain}	{@link}与连接标签相同，除了代码字体外，以纯文本显示。标签是纯文本时颇有用
{@docRoot}	表示从任何生成的页面生成的文档（目标）根目录的相对路径（版权标明）
{@inheritDoc}	继承父级的注释标签

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&lt;String&gt; entity = new HttpEntity&lt;String&gt;(helloWorld, headers); * URI location = template.postForLocation("http://example.com", entity); * </pre> * or * <pre class="code"> * HttpEntity&lt;String&gt; 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"> * &#64;RequestMapping("/handle") * public HttpEntity&lt;String&gt; handle() { * HttpHeaders responseHeaders = new HttpHeaders(); * responseHeaders.set("MyResponseHeader", "MyValue"); * return new HttpEntity&lt;String&gt;("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));
	}
}
复制代码

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

1. 简述

2. 命令用法

3. 主要标记简介

3.1 @see

3.1.1 @see "字符串"

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

3.1.3 @see package.class #成员 标签

3.2 @author

3.3 @version

3.4 {@link}

3.5 {@value}

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

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

3.6 @param

3.7 @return

3.8 @throws、@exception

3.9 {@inheritDoc}

4. 各文档注释

4.1 包文档标签

4.2 类和接口文档标记

4.3 字段文档标签

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

5. 示例

3.1.3 @see package.class #成员标签