Javadocs
Javadoc 注释是特殊的注释，用于为其下方的代码元素提供描述。 它们以 /** 开头，以 */ 结束，并可以包含带有特定元数据的 @ 标记。
Javadoc 是 Java 提供的工具，可从 Javadoc 注释生成 HTML 文档。 您可以使用 JDK 附带的 Javadoc 工具，为您的项目生成 API 参考。 IntelliJ IDEA 提供了与该工具的集成，并允许您直接从 IDE 中 构建参考指南。
了解有关 Javadocs、样式指南、术语和约定的正确格式的更多信息，请参阅 如何为 Javadoc 工具编写文档注释。
编写 Javadoc 注释
您可以手动输入 Javadoc 注释，或在 IntelliJ IDEA 中使用内置操作将其添加到代码中。
当您在方法上使用 Javadoc 操作时，IDE 会根据方法结构自动在注释中插入所需的标签：针对每个参数使用 @param ，如果方法有返回值则插入 @return ，针对方法可能抛出的每个异常插入 @throws。
使用自动补全添加 Javadoc 注释。
在声明之前输入
/**并按 Enter。 IDE 会为您自动完成文档注释。
使用上下文操作添加 Javadoc 注释
将文本光标放于编辑器中的声明处。
按 Alt+Enter 并选择 添加Javadoc。
Javadoc 注释中的格式设置
您可以使用 HTML 标签和 Javadoc 专用标签格式化 Javadoc 注释。 本章节列举了一些最常用的标签。
HTML 标签：
使用
<p>表示段落。使用
<h1>、<h2>等表示标题。使用
<img>添加图片，例如：<img src="jb_logo.png"/>。使用
<pre>保留空格。对于列表，使用
<ul>（无序）、<ol>（有序）、<li>表示有序和无序列表中的项目。
内联 Javadoc 标签：
使用
{@code text}将内联文本格式化为代码。使用
{@literal text}显示特殊字符，例如 < 和 >。使用
{@link ClassName}插入指向其他类或方法的超链接。
块级 Javadoc 标签：
使用
@param name description描述方法参数。使用
@return description描述方法的返回值。使用
@deprecated reason标记方法或类为已弃用。使用
@author name指定类或接口的作者。
在编辑器中渲染 Javadocs
IntelliJ IDEA 允许您在编辑器中渲染 Javadoc 注释。 渲染的注释更易于阅读，可以点击链接跳转到相关网页，并且不会使代码因额外标签而变得杂乱。
要渲染 Javadoc 注释，请点击装订区域的 
切换渲染视图 （或按 Ctrl+Alt+Q）。 要编辑注释，请点击 
切换渲染视图。
默认渲染 Javadoc 注释
您可以将 IDE 配置为始终在编辑器中渲染 Javadoc 注释。
在装订区域内，右键点击
切换渲染视图 （或 切换渲染视图 ），然后选择 呈现所有文档注释。或者，打开 设置 （Ctrl+Alt+S ），转到 ，并选择 渲染文档注释。
要编辑已渲染的 Javadoc 注释，请点击装订区域的 
切换渲染视图。
更改已渲染 Javadoc 注释的字体大小
右键点击已渲染的 Javadoc 注释并选择 调整外观。
在弹出的窗口中，调整 字体大小 滑块。
请注意，渲染的注释使用与 快速文档弹出窗口相同的字体大小。
生成 Javadoc 参考
IntelliJ IDEA 提供了一个工具，允许您为项目生成 Javadoc 参考。
在主菜单中，前往 。
在打开的对话框中，选择一个范围：您想要生成参考的文件或目录集。
在 输出目录(D) 中，指定生成文档将放置的文件夹。
从 可见性级别 列表中选择将在生成的文档中包含的成员可见性级别：
public(B) ：仅包含 public 类和成员。 该级别对应于
-publicJavadoc 参数。protected(T) ：仅包含 public 和 protected 类及成员。 该级别对应于
-protectedJavadoc 参数。软件包 ：包含除 private 之外的所有类和成员。 该级别对应于
-packageJavadoc 参数。私有(I) ：包括所有类和成员。 该级别对应于
-privateJavadoc 参数。
您可以指定语言环境（例如
en_US.UTF-8）、命令行参数以及最大堆大小。 有关所有控件的说明，请参阅 参考资料。点击 生成 生成参考。
参考：生成 JavaDoc 对话框
生成JavaDoc 对话框中的控件对应于 Javadoc 实用工具的选项和标签。
条目 | 描述 |
|---|---|
JavaDoc 作用域 | 请在此区域指定要生成 Javadoc 的文件、文件夹和包的子集。 这个 scope可以是整个项目、最近修改的文件、当前文件、自定义 scope 等等。 |
包含测试代码(T) | 将测试的文档注释包含在生成的 Javadoc 中。 |
在-sourcepath 中包含 JDK 和库源 | 如果选中此复选框，则 JDK 和库源路径将传递到 Javadoc 工具。 有关更多信息，请参阅 Javadoc 文档。 |
链接到JDK 文档 (使用 -link 选项) | 如果选择此复选框，对 JDK 类和包的引用将变成链接，这对应于使用 Javadoc 工具的 -link 选项。 只有在 文档路径 选项卡的 SDK 设置中指定了在线文档链接时，此复选框才会启用。 如需更多信息，请参阅 Javadoc 文档。 |
输出目录(D) | 指定生成的文档将存储的目录的完全合格路径。 可手动输入路径，或点击 |
可见性级别 | 指定您要在生成的文档中包含的成员可见性级别：
|
生成层次结构树 | 生成类层次结构。 如果清除此复选框，将把 |
生成导航栏 | 生成导航栏。 如果清除此复选框，将把 |
生成索引 | 生成文档索引。 如果清除此复选框，将把 |
每个字母单独的索引 | 为每个字母生成一个单独的索引文件。 如果清除此复选框，将把 仅当选中了 生成索引 复选框时，此复选框才可用。 |
@使用 | 请记录 class 和 package 的使用情况。 选中后，复选框将对应 |
@author | 包含 |
@version | 包含 |
@deprecated | 请包含 |
弃用列表 | 生成过时列表。 当复选框被清除时， 仅当选中了 @deprecated 复选框时，此复选框才可用。 |
区域设置(L) | 输入所需的区域设置。 |
命令行实参 | 输入要传递给 Javadoc 的附加参数。 请使用命令行语法。 |
堆大小上限(M) | 请输入 Java 虚拟机运行 Javadoc 使用的最大堆大小（以 Mb 为单位）。 |
生成文档并用浏览器打开(G) | 自动在浏览器中打开生成的 Javadoc。 |
在 Javadocs 中使用自定义标签
除了预定义标签外，您还可以在 Javadoc 注释中使用自定义标签。 以后生成 Javadoc 参考时，您可以选择 在生成的文档中包含自定义标签。
识别自定义标签
当您第一次使用自定义标签时， Javadoc 声明问题 检查会在编辑器中将其高亮显示为错误标签。 为避免这种情况，请将标签添加到已识别标签列表中。
将文本光标放在您的自定义标签处，按 Alt+Enter 并选择 将"@tagname"添加到自定义标签。
或者，打开 设置 （Ctrl+Alt+S ），然后转到 。 在列表中找到 Javadoc 声明问题 检查，并将您的标签添加到 附加Javadoc 标记 列表中。
将自定义标签包含在 Javadoc 引用中
要在 HTML Javadoc 引用中包含您的自定义标签，请将它们作为命令行参数添加。
请转到 并在 命令行实参 字段中指定
-tag tagname:Xaoptcmf:"taghead"。示例：
-tag location:a:"Development Location:"Xaoptcmf决定标签在源代码中允许放置的位置。 您可以在所有地方使用a来允许该标签。 如需了解更多有关 Javadocs 区块标签的信息，请参阅 Javadoc 文档。按照 生成 Javadoc 参考 中描述的配置其他选项，并生成参考指南。
标签中的信息显示在对应的页面上。
自定义 Javadoc 代码样式
Javadoc 代码样式定义了 IntelliJ IDEA 在编辑器中格式化 Javadoc 注释的方式。
打开 设置 （Ctrl+Alt+S ），然后转到 。
定位到 JavaDoc 标签页。
根据需要配置 代码样式设置。 使用对话框右侧预览更改。
参考：Javadoc 代码样式设置
条目 | 描述 |
|---|---|
对齐 | 定义 Javadoc 注释的对齐方式。
|
空行 | 定义在 Javadoc 注释中应插入空行的位置。
|
无效标签 | 在此区域内，定义是否应保留无效的选项卡。
|
其他 | 在此区域中，为 Javadoc 注释指定附加格式化选项。
|
在库中使用 Javadocs
除了代码中的 Javadoc 注释外，IntelliJ IDEA 还可以渲染项目所用库的 Javadocs。 只要在项目设置的库中已 添加 Javadocs ，就可以直接在编辑器中查看任何符号或方法签名的外部 Javadocs。
在 IntelliJ IDEA 中查看库 Javadocs
调用 快速文档 弹窗：
在编辑器中将鼠标悬停在所需符号上。
或者，将文本光标置于符号处，然后按 Ctrl+Q （）。
要在专用工具窗口中打开文档，请再按一次 Ctrl+Q。
如果项目中的某个库通常会提供 Javadocs，但在 IntelliJ IDEA 中找不到，可以下载 Javadocs（使用内置下载选项）或手动添加。
下载库 Javadocs
给库添加 Javadocs 的最快方法是下载它们。 下载选项的位置因所用构建工具的不同而有所区别。
打开 Maven 工具窗口。
点击
下载源代码和/或文档 并选择 下载文档。
在编辑器中，将鼠标悬停在来自库的符号或方法签名上。
在弹出的窗口中，点击
下载文档。
打开 项目结构 对话框（Ctrl+Alt+Shift+S ）并选择 库。
选择所需库，在对话框右侧点击 编辑。
在打开的对话框中，选择 下载 Javadocs 并点击 OK。
应用更改并关闭对话框。
手动为库添加 Javadocs
您可以通过提供外部 URL 或添加包含 Javadocs 的 JAR 文件，手动为库添加 Javadocs。
指定 Javadocs URL
打开 项目结构 对话框(Ctrl+Alt+Shift+S )并转到 库。
从列表中选择一个库，然后在对话框右侧部分点击
指定文档 URL。在打开的对话框中，输入文档 URL 并点击 OK。
应用更改并关闭对话框。
添加带有 Javadocs 的 JAR 文件
打开 项目结构 对话框(Ctrl+Alt+Shift+S )并转到 库。
从列表中选择一个库，然后在对话框右侧部分点击
添加。 
在打开的对话框中，选择包含文档的 JAR 文件并点击 打开。
应用更改并关闭对话框。
排查 Javadoc 问题
Javadoc 检查问题
如果方法签名已更改，IntelliJ IDEA 会高亮显示与方法签名不匹配的标签，并建议快速修复。
使用上下文操作修复
将文本光标放置在标记处，按 Alt+Enter ，然后选择一个操作。 您可以更改标签或将其删除。
使用 修复文档注释 操作修复
将文本光标放在标签上并按 Ctrl+Shift+A。
输入
fix doc comment并按 Enter。
Javadoc 生成错误
如果 IntelliJ IDEA 在 生成 Javadoc 参考时遇到错误，会在 运行 工具窗口（Alt+4 ）显示错误详情。
修复因 UTF-8 编码导致的错误语言区域名称
如果遇到 javadoc: error – Malformed locale name: en_US.UTF-8 ，请尝试将 UTF-8 编码移至命令行参数：
在主菜单中，前往 。
清除 区域设置(L) 字段。
在 命令行实参 字段中，输入
-encoding utf8 -docencoding utf8 -charset utf8。-encoding：用于源文件的编码。-docencoding：应在输出 HTML 文件中使用的编码。-charset：Javadoc 应插入到每个输出文件 HTML 标头部分的字符集。
请重新生成 Javadoc 参考。