Article Directory
All knowledge system articles have been included in GitHub , welcome to Star!
GitHub address: https://github.com/Ziphtracks/JavaLearningmanual
Search and follow the WeChat public account "Code Out Offer", Brother Z will send you learning welfare resources!
Javadoc documentation
1. What is a Javadoc document
Javadoc is a technology provided by Sun. It extracts annotations such as classes, methods, and members from the program source code to form an API help document that matches the source code. In other words, as long as the program is annotated with a set of specific tags, after the program is written, the development document of the program can be formed at the same time through Javadoc.
The javadoc command is used to generate your own API documentation. How to use it: Use the command line to enter the directory where the target file is located
javadoc +文件名.java.
Two, Javadoc documentation comments
Java annotation classification:
//注释内容: Single-line comment, no line break/*注释内容*/: Multi-line comments, support line break- The format of Javadoc document comments is as follows, line breaks are supported, and Javadoc documents can be generated [Key]
/**
* 文档注释
*/
Three, common annotation document mark
Refer to the official documentation: javadoc-The Java API Documentation Generator
| Frequently used labels | Description |
|---|---|
| @author Author | Author ID |
| @version version number | version number |
| @param parameter name description | The name and description of the method's entry parameters, if there are special requirements for entry, you can comment here. |
| @return description | Notes on function return value |
| @deprecated expired text | Identifies that with the improvement of the program version, the current API has expired, just to ensure that the compatibility still exists, to inform developers that this API should not be used anymore. |
| @throws exception class name | The exception thrown by the constructor or method. |
| @exception Exception class name | 同@throws。 |
| @see quote | View related content, such as classes, methods, variables, etc. |
| @since description text | After which version of the API is developed and supported. |
| {@link包.类#member tag} | Link to the document corresponding to a particular member. |
| {@value} | When annotating a constant, if you want to include its value in the document, use the tag to refer to the value of the constant. |
| Infrequently used labels | Description |
| @serial | Describe a serialized attribute |
| @serialField | Describe an ObjectStreamField component |
| @serialData | Explain the data written by the writeObject() and writeExternal() methods |
| {@docRoot} | Specifies the path of the root directory of the current document |
| {@inheritDoc} | Annotations inherited from the immediate parent class |
| {@literal} | Display text without interpreting it as HTML tags or nested javadoc tags. |
| {@code} | Display the text in font codewithout interpreting the text as HTML tags or nested Javadoc tags. |
Four, Javadoc option description
Javadoc command format: javadoc [option] [package name] [source file]
4.1 Option description
| Options | Description |
|---|---|
| -overview | <file> reads the overview document of the HTML file |
| -public | Show only public classes and members |
| -protected | Show protected/public classes and members (default) |
| -package | Show packages/protected/public classes and members |
| -private | Show all classes and members |
| -help | Show command line options and exit |
| -doclet | <class> Generate output by replacing doclet |
| -docletpath | <path> specifies the location to find doclet class files |
| -sourcepath | <path list> specify the location to find the source file |
| -classpath | <path list> Specify the location to find user class files |
| -exclude | <软件包列表> 指定要排除的软件包的列表 |
| -subpackages | <子软件包列表> 指定要递归装入的子软件包 |
| -breakiterator | 使用 BreakIterator 计算第 1 句 |
| -bootclasspath | <路径列表> 覆盖引导类加载器所装入的类文件的位置 |
| -source | <版本> 提供与指定版本的源兼容性 |
| -extdirs | <目录列表> 覆盖安装的扩展目录的位置 |
| -verbose | 输出有关 Javadoc 正在执行的操作的消息 |
| -locale | <名称> 要使用的语言环境，例如 en_US 或 en_US_WIN |
| -encoding | <名称> 源文件编码名称 |
| -quiet | 不显示状态消息 |
| -J<标志> | 直接将 <标志> 传递给运行时系统 |
| -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> 的 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>指定输出的字符编码 |
4.2 标记的顺序
- @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)
4.3 可以多次使用标记
- @author 标记应按时间顺序排列，并用逗号分隔。
- @ param 标记应该在参数声明的顺序列出，这使它更容易在视觉上与声明相匹配的列表。
- @throws 标记 (类同 @exception)应按字母顺序列出的例外的名字。
- @see 标记遵循由近到远，参数由少到多，由上到下的顺序。
五、命令生成doc文档
5.1 测试所在的目录结构
项目所在目录为：d:\Code\javase\firstdoc
目录结构如下：
创建的两个类均有javadoc文档注释如下：
Calculator：
package com.mylifes1110.java;
/**
* @author Ziph
* @since 1.8
* @version 1.0
*/
public class Calculator {
/**
* 无参构造器
*/
public Calculator() {
}
/**
* 计算两个数字相加
* @param num1 整数1
* @param num2 整数2
* @return 两个整数之和
*/
public int add(int num1, int num2) {
return num1 + num2;
}
}
CalculatorTest：
package com.mylifes1110.test;
/**
* @author Ziph
* @since 1.8
* @version 1.0
*/
public class CalculatorTest {
/**
* 测试
*/
public CalculatorTest() {
}
}
5.2 命令生成Javadoc文档步骤
生成好的Javadoc文档index.html是文档入口，打开后即可看见doc文档内容。
方式一：单个或多个.java文件生成doc文档
这里我们生成Calculator.java的doc文档，首先先进入到Calculator.java所在目录，然后去此文件夹中打开DOS命令窗口，此方式生成的doc文档是默认创建了.java文件所在的包，输入以下命令即可：
命令格式： javadoc -d 文档存储目录 -encoding utf-8 -charset utf-8 Xxx.java
参数说明：
- -d 指定API文档的输出目录，默认是当前目录。建议总是指定该参数。
- -encoding UTF-8 表示你的源代码（含有符合 JavaDoc 标准的注释）是基于 UTF-8 编码的，以免处理过程中出现中文等非英语字符乱码
- -charset UTF-8 表示在处理并生成 JavaDoc 超文本时使用的字符集也是以 UTF-8 为编码，目前所有浏览器都支持 UTF-8，这样最具有通用性，支持中文非常好
注意： 如果此文件夹内有多个.java文件需要生成，我们可以在指定.java文件的时候使用
*.java。这里utf-8编码相关是指定文档的编码字符集，如果与项目或系统编码不一致可能会造成生成的doc文档乱码。
javadoc -d d:\Code\javase\firstdoc\doc -encoding utf-8 -charset utf-8 Calculator.java
方式二：指定源文件路径生成doc文档
由于方式一每次生成doc文档都需要进入到.java文件所在目录操作，借此我们简化了此操作。使用doc文档选项生成。首先，我们这次只需要进入到项目内的第一层文件夹，在此文件夹中就可以看到src了，然后在此文件夹中打开DOS命令窗口，此方式生成的doc文档可以用doc文档选项来指定源文件所在生成的目录的包，输入以下命令即可：
命令格式： javadoc -d 文档存储目录 -encoding utf-8 charset utf-8 -sourcepath 源文件所在目录 -subpackages 需要生成的源文件目录包 -version -author
参数说明：
- -d 指定API文档的输出目录，默认是当前目录。建议总是指定该参数。
- -encoding UTF-8 表示你的源代码（含有符合 JavaDoc 标准的注释）是基于 UTF-8 编码的，以免处理过程中出现中文等非英语字符乱码
- -charset UTF-8 表示在处理并生成 JavaDoc 超文本时使用的字符集也是以 UTF-8 为编码，目前所有浏览器都支持 UTF-8，这样最具有通用性，支持中文非常好
- -sourcepath 指定源代码路径，默认是当前目录。 此参数通常是必须的。
- -subpackages 以递归的方式处理各子包。如果不使用本参数，每次只能处理一个子包（或需手工列出所有子包）。
- -author 可以将作者信息（@author ***）导出到最终生成的API文档中。
- -version 可以生成版本信息。
- -windowtitle 设置API文档的浏览器窗口标题。
- -doctitle 指定概述页面的标题。
- -header 指定页面的页眉。
javadoc -d ./doc -encoding utf-8 -charset utf-8 -sourcepath d:\Code\javase\firstdoc\src -subpackages com.mylifes1110.test -version -author
查看生成的doc目录
六、IDEA生成doc目录
- 首先，打开IDEA，并找到
Tools -> Generate JavaDoc...
- 生成Doc文档中的选项操作
Loacle： 这是一个可选项，表示的是需要生成的 JavaDoc 以何种语言版本展示，根据 javadoc.exe 的帮助说明，这其实对应的就是 javadoc.exe 的 -locale 参数，如果不填，默认可能是英文或者是当前操作系统的语言。但是我们也可以填
zh_CN。
- IDEA生成Doc文档过程
- 查看生成后的Doc文档
