Javadoc 文件的生成(Javadoc I Documentation Generator)

Javadoc是一个从Java源代码创建HTML格式文档的工具。 该实用程序检查源代码，提取文档中的特殊标记信息，然后生成汇总软件的Web页面。

文档注释（也称为doc注释）指定了javadoc工具要处理的注释的格式。 称为标签的特殊标签也由javadoc解析。 同时，doc注释和标签可用于构建完整的Java应用程序编程接口（API）规范。 Java API是如何使用类的规范。

Javadoc可以在包或单个文件（或两者）上运行。 它每次都会生成结构良好的单个文档。 但是，javadoc不支持增量添加。

Javadoc是Java软件开发工具包（SDK）的标准部分。 工具可执行文件javadoc.exe与javac编译器和java执行工具一起驻留在安装目录的bin文件夹中。 因此，如果您能够使用命令行编译和执行代码，javadoc也应该可以工作。

使用javadoc很简单; 它非常类似于编译java源文件。 例如：

javadoc myfile.java

javadoc命令还可以指定选项和包名称。 源文件名必须包含.java扩展名（类似于javac编译器命令）。

doc 注释

文档注释细分为描述和标记。 描述应提供所解释代码的功能的概述。 标签解决了功能的细节，例如代码版本（用于类或接口）或返回类型（用于方法）。

Javadoc处理在/ **，开始标记和* /，结束标记之间放置的代码注释。 允许注释跨越多行，其中每行以*字符开头，该字符与它们之前的任何空格一起被工具丢弃。 允许这些注释包含HTML标记。 例如：

/**
* This is an <strong>example</strong> document comment.

*/

应仔细考虑注释的放置。 javadoc工具自动将每个doc的第一个句子复制到HTML文档顶部的摘要中。 该句子在*字符后面的任何空格后开始，并在第一个句点结束。 以下描述应简明扼要。 仅当文档注释紧接在类，构造函数，方法，接口或字段声明之前放置时，才会识别它们。

在描述中使用HTML应限于正确的注释分离和显示而不是样式。 Javadoc使用某些标记自动构建文档 - 例如，标题标记。 适当使用段落或列表标签（有序/无序）应提供令人满意的格式。

标签

标签包含在文档评论中。 每个标记必须以单独的行开头，因此必须以*字符开头。 标签区分大小写，以@符号开头。

某些情况下需要某些标签。 必须为每个参数提供@param标记，并用于描述参数的用途。 必须为返回void之外的任何方法提供@return标记，以描述该方法返回的内容。 @author类和@version标记仅用于类和接口。

图I.1列出了javadoc注释中使用的各种标记。

请注意图I.1中列出的两种不同类型的标记。 以@符号开头的块标签（例如@author）必须放在标

签部分

标签名称	描述
@author	插入带有指定文本的“作者”条目。
{@code}	与<code> {@ literal} </ code>相同。
@deprecated	插入带有指定文本的粗体“Deprecated”条目。
{@docRoot}	指向文档根目录的相对链接。
@exception	见@throws。
{@inheritDoc}	从最近的继承类或已实现的接口复制文档，以便重用更高级别的类的更一般注释。
{@link}	插入HTML文档的超链接。使用：{@ link name url}。
{@linkPlain}	与{@link}相同，但显示为纯文本。使用：{@ linkPlain link label}。
{@literal}	标签中包含的文本按字面表示，包含任何HTML。例如，将显示{@literal <td> TouchDown} as <td> TouchDown（<td>未解释为表格单元格）。
@param	插入“参数”部分，列出并描述特定构造函数/方法的参数。
@return	插入“返回”部分，该部分列出并描述特定构造函数/方法的任何返回值。使用：@return描述。如果包含在具有void返回类型的方法的注释中，则会引发错误。
@see	包含“另请参阅”注释，其中的链接指向包含更多信息的文档。使用：@see链接。
@serial	用于可序列化字段。使用：@serial文本。
@serialData	用于记录用于描述writeObject，readObject，writeExternal和readExternal方法所写数据的文档。 使用：@serialdata文本。
@serialField	用于评论ObjectStreamField。使用：@serialField名称类型描述。
@since	插入一个新的“Since”标题，用于表示何时首次引入特定功能。使用：@since文字。 抛出： 包括“投掷”标题。使用：@throws名称描述。
@throws	包括“抛出”标题。使用：@throws名称描述。
{ @value}	返回它引用的代码元素的值。使用：@value代码 - 成员标签。
@version	使用-version命令行选项时添加“版本”标题。使用：@version文本

图i.1 javadoc注释中使用的各种标记

以下是主要说明。 包含在{和}分隔符中的内联标记可以放在描述部分的任何位置或块标记的注释中。 例如：

/**

•  This is an <strong>example</strong> document comment.
•  The {@link Glossary} provides definitions of types used.
•  
•  @author Sebastian Niezgoda
• /

生成的文件

javadoc工具分析java源文件或包，并为每个类生成一个由三部分组成的HTML文档。 HTML文件通常称为文档文件。 它包含有关从代码中包含的doc注释派生的类文件的干净组织信息。

该文档的第一部分包含该类的整体描述。 首先出现类名，然后是继承关系的图形表示。 接下来显示一般描述，其从每个文档评论实体的第一个句子中提取（如前所述）。

接下来，提供构造函数和方法的列表。 将列出源文件中包含的所有构造函数和方法的签名以及单句描述。 构造函数/方法的名称是指向文档第三部分中更详细描述的超链接。

最后，提供了对方法的完整描述。 同样，首先提供签名，然后提供对实体的解释，但这次没有单句限制，这是从文档注释中获得的。 如果适用，相关章节中提供了参数和返回值列表及其说明。

HTML文档广泛使用超链接来提供必要的附加信息，例如使用@see标记，以及导航目的。 页面的页眉和页脚是导航栏，带有以下链接：

■包提供包中包含的类列表以及每个类的简短目的和描述。

■树呈现包中类的可视层次结构。 每个类名都是相应文档HTML文件的链接。

■不推荐使用的列表包含在包中包含的任何类文件中使用的已弃用的功能。

■索引提供了包中的类，构造函数和方法的字母顺序列表。 类名也与类的简短目的和描述相关联。 类名的每个外观都是指向相应HTML文档的链接。 每个构造函数和方法的签名都是指向相应详细描述的链接。 签名列表旁边的一句话描述将构造函数/方法与适当的类相关联。

■帮助加载帮助页面，其中包含有关使用和导航HTML文档的操作说明。

可以使用或不使用框架查看所有页面。 每个类摘要都有可用于快速访问文档任何部分的链接（如上所述）。

输出内容可能通过执行javadoc工具时使用的命令行选项（见上文）生成。 默认情况下，如果未指定任何选项，则返回的输出等效于使用-protected选项。 选项包括：

■private显示所有类，方法和变量。

■public仅显示公共类，方法和变量。

■protected仅显示受保护的和公共的类，方法和变量。

■help提供在线帮助。

■关键字包括生成的输出文件的HTML元标记，以帮助进行搜索。

原文如下：

Javadoc is a tool for creating documentation in HTML format from Java source code. The utility examines the source code, extracts specially marked information in the documentation, and then produces Web pages that summarize the software.

Documentation comments, also referred to as doc comments, specify the for- mat for comments to be processed by the javadoc tool. Special labels called tagsare also parsed by javadoc. Together, doc comments and tags can be used to construct a complete Java application programming interface (API) specification. A Java API is a specification of how to work with a class.

Javadoc can be run on packages or individual files (or both). It produces a well-structured, single document each time. However, javadoc does not support incremental additions.

Javadoc comes as a standard part of the Java Software Development Kit (SDK). The tool executable, javadoc.exe, resides in the bin folder of the installation direc- tory along with the javac compiler and java execution tool. Therefore, if you are able to compile and execute your code using the command line, javadoc should also work.

Using javadoc is simple in its plain form; it is very much like compiling a java source file. For example:

javadoc myfile.java

The javadoc command may also specify options and package names. The source file name must contain the .java extension (similar to the javac compiler command).

723

724 a p p e n d i x i Javadoc Documentation Generator

doc Comments

The document comments are subdivided into descriptions and tags. Descriptions should provide an overview of the functionality of the explained code. Tags address the specifics of the functionality such as code version (for classes or inter- faces) or return types (for methods).

Javadoc processes code comments placed between /**, the beginning tag, and*/, the end tag. The comments are allowed to span multiple lines where each line begins with a * character, which are, along with any white space before them, discarded by the tool. These comments are allowed to contain HTML tags. For example:

/**
* This is an <strong>example</strong> document comment. */

Comment placement should be considered carefully. The javadoc tool auto- matically copies the first sentence from each doc to a summary at the top of the HTML document. The sentence begins after any white space following the* character and ends at the first period. The description that follows should be concise and complete. Document comments are recognized only if they are placed immediately before a class, constructor, method, interface, or field declaration.

The use of HTML inside the description should be limited to proper comment separation and display rather than styling. Javadoc automatically structures the document using certain tags—for example, heading tags. Appropriate use of paragraph or list tags (ordered/unordered) should provide satisfactory formatting.

Tags

Tags are included in a doc comment. Each tag must start on a separate line, hence it must be preceded by the * character. Tags are case sensitive and begin with the@ symbol.

Certain tags are required in some situations. The @param tag must be supplied for every parameter and is used to describe the purpose of the parameter. The@return tag must be supplied for every method that returns anything other thanvoid, to describe what the method returns. The @author class and the @versiontags are required for classes and interfaces only.

Figure I.1 lists the various tags used in javadoc comments.

Note the two different types of tags listed in Figure I.1. The block tags,which begin with the @ symbol (e.g., @author), must be placed in the tag section

a p p e n d i x i Javadoc Documentation Generator 725

Tag Name Description
@author	Inserts an “Author” entry with the specified text.
{ @code}	Same as <code>{@literal}</code>.
@deprecated	Inserts a bold “Deprecated” entry with the specified text.
{ @docRoot}	Relative link to the root of the document.
@exception	See @throws.
{ @inheritDoc}	Copies documentation from the closest inherited class or implemented interface where used allowing for more general comments of hierarchically higher classes to be reused.
{ @link}	Inserts a hyperlink to an HTML document. Use: {@link name url}.
{ @linkPlain}	Same as {@link} but is displayed as plain text. Use: {@linkPlain link label}.
{ @literal}	Text enclosed in the tag is denoted literally, as containing any HTML. For example, {@literal <td> TouchDown} would be displayed as <td> TouchDown (<td> not interpreted as a table cell).
@param	Inserts a “Parameters” section, which lists and describes parameters for a particular constructor/method.
@return	Inserts a “Returns” section, which lists and describes any return values for a particular constructor/method. Use: @return description. An error will be thrown if included in a comment of a method with the void return type.
@see	Included a “See Also” comment with a link pointing to a document with more information. Use: @see link.
@serial @serialData @serialField	Used for a serializable field. Use: @serial text. Used to document used to describe data written by the writeObject, readObject, writeExternal, and readExternal methods. Use: @serialdata text. Used to comment on the ObjectStreamField.Use: @serialField name type description.
@since	Inserts a new “Since” heading that is used to denote when particular features were first introduced. Use: @since text.
@throws	Includes a “Throws” heading. Use: @throws name description.
{ @value}	Returns the value of a code element it refers to. Use: @value code- member label.
@version	Add a “Version” heading when the –version command–line option is used. Use: @version text.

Figure i.1 Various tags used in javadoc comments

726 a p p e n d i x i Javadoc Documentation Generator

following the main description. The inline tags, enclosed in the { and } delimiters, can be placed anywhere in the description section or in the comments for block tags. For example:

/**

• *  This is an <strong>example</strong> document comment.

• *  The {@link Glossary} provides definitions of types used. *

• *  @author Sebastian Niezgoda */

  Files generated

  The javadoc tool analyzes a java source file or package and produces a three- part HTML document for each class. The HTML file is often referred to as a documentation file. It contains cleanly organized information about the class file derived from the doc comments included in the code.

  The first part of the document contains an overall description of the class. The class name appears first followed by a graphical representation of the inheritance relationships. A general description is displayed next, which is extracted from the first sentence of each doc comment entity (as discussed previously).

  Next, a list of constructors and methods is provided. The signatures of all the constructors and methods included in the source file are listed along with one- sentence descriptions. The name of the constructor/method is a hyperlink to a more detailed description in the third part of the document.

  Finally, complete descriptions of the methods are provided. Again, the signature is provided first followed by an explanation of the entity, but this time without the one-sentence limit, which is obtained from the doc comments. If applicable, a list of parameters and return values, along with their descriptions, is provided in the respective sections.

  The HTML document makes extensive use of hyperlinks to provide necessary additional information, using the @see tag for example, and for navigational pur- poses. The header and the footer of the page are navigation bars, with the following links:

  • Package provides a list of classes included in the package along with a short purpose and description of each class.

  • Tree presents a visual hierarchy of the classes within the package. Each class name is a link to the appropriate documentation HTML file.

  • Deprecated lists functionality that is considered deprecated that is used in any of the class files contained in the package.

• Index provides an alphabetical listing of classes, constructors, and methods in the package. The class name is also associated with a short purpose and description of the class. Each appearance of the class name is a link to the appropriate HTML documentation. The signature of every constructor and method is a link to the appropriate detailed description. A one-sentence description presented next to the signature listing associates the constructor/ method with the appropriate class.

• Help loads a help page with how-to instructions for using and navigating the HTML documentation.

  All pages could be viewed with or without frames. Each class summary has links that can be used to quickly access any of the parts of the document (as described above).

  The output content could be somewhat generated by command-line options (see above) used when executing the javadoc tool. By default, if no options are specified, the output returned is equivalent to using the −protected option. The options include:

• private shows all classes, methods, and variables.

• public shows only public classes, methods, and variables.

• protected shows only protected and public classes, methods, and variables.

• help presents the online help.

• keywords includes HTML meta tags to the output file generated to assist with searching.