Javadocs
Javadoc 是一款 JDK 工具，可为项目生成 API 参考文档。 它依赖于文档注释，这些注释紧接在所描述的声明之前，旨在在代码之外共享，并支持高级格式设置选项。 Javadocs 被视为为 Java 编码编写文档的行业标准。
IntelliJ IDEA 为 Javadoc 提供以下支持：
用于 生成 Javadoc 注释存根的操作
检查及 Javadoc 注释问题的快速修复
在编辑器中 渲染 Javadoc 注释
项目中基于 Javadoc 注释 生成 API 参考的对话框
在 IDE 中 渲染库 Javadoc
文档注释也可用于 JavaScript、 Python、 Ruby、 PHP 和 Kotlin。
编写 Javadoc 注释
为帮助更快地为你的编码编写文档，IntelliJ IDEA 可为声明生成 Javadoc 注释存根。 这对于方法尤其有用，IDE 会根据方法结构自动插入所需的 Javadoc 标记：每个形参 @param ，如果方法返回值，则插入 @return ，每个方法可能抛出的异常插入 @throws。
IntelliJ IDEA 支持以传统和 Markdown 两种样式生成 Javadoc 注释，这两种样式使用不同的格式设置语法。 有关更多信息，请参见 Javadoc 注释中的格式设置。
使用自动补全添加 Javadoc 注释
要插入传统文档注释，在声明前输入
/**，然后按 Enter。
要插入 Markdown 文档注释，在声明前输入
///，然后按 Enter。
使用上下文操作添加 Javadoc 注释
将文本光标置于声明名称处。
按 Alt+Enter 并选择 添加 Javadoc。
使用命令补全添加 Javadoc 注释
将文本光标置于声明名称末尾。
输入
..并选择 添加 Javadoc。
Javadoc 注释中的格式设置
自 Java 23 起，Javadoc 支持两种注释风格：传统和 Markdown。 两种样式都支持使用 HTML 标记以及 Javadoc 特定的块标记和内联标记进行格式设置。 Markdown 文档注释还支持使用 Markdown 语法进行格式设置，可以用它替代最常见的 HTML 标记和某些内联 Javadoc 标记。
要了解详情，包括 Javadoc 注释中的结构、语法和受支持的标记，请参阅 标准 Doclet 的 JavaDoc 文档注释规范 (oracle.com)。
下表列出了 Javadoc 注释中常用的标记元素，并提供了传统注释样式和 Markdown 注释样式的示例。
Element | Javadoc 注释示例 |
|---|---|
标题 |
/**
* <h1>First-level heading</h1>
* <h2>Second-level heading</h2>
*/
/// # First-level heading
/// ## Second-level heading
|
段落分隔 |
/**
* This is the first paragraph.
* <p>
* This is the second paragraph.
*/
/// This is the first paragraph.
///
/// This is the second paragraph.
|
换行 |
/**
* Accepted formats:<br>
* yyyy-MM-dd<br>
* dd.MM.yyyy
*/
/// Accepted formats:\
/// yyyy-MM-dd\
/// dd.MM.yyyy
|
强调 |
/**
* <b>Note:</b> The returned price is <i>not</i> rounded.
*/
/// **Note:** The returned price is _not_ rounded.
|
特殊字符 |
/**
* Removes all {@literal <script>} tags from the input.
* The input length must be {@literal >} 0 and {@literal <=} 10,000 characters.
*/
/// Removes all \<script> tags from the input.
/// The input length must be > 0 and <= 10,000 characters.
|
图像 |
/**
* <img src="doc-files/IntelliJ_IDEA_icon.svg" alt="IntelliJ IDEA logo">
*/
/// 
|
链接到另一个代码元素 |
/**
* Returns the final price of the {@link ShoppingItem}.
* The discount is applied by {@link PriceCalculator#applyDiscount(double, double)}.
*/
/// Returns the final price of the [ShoppingItem].
/// The discount is applied by [PriceCalculator#applyDiscount(double, double)].
|
外部链接 |
/**
* Learn more from <a href="https://www.jetbrains.com.cn/help/idea/getting-started.html">official IntelliJ IDEA documentation</a>.
*/
/// Learn more from [official IntelliJ IDEA documentation](https://www.jetbrains.com.cn/help/idea/getting-started.html).
|
列表 |
/**
* <ul>
* <li>First element of an unordered list</li>
* <li>Second element of an unordered list</li>
* </ul>
*
* <ol>
* <li>First element of an ordered list</li>
* <li>Second element of an ordered list</li>
* </ol>
*/
/// - First element of an unordered list
/// - Second element of an unordered list
///
/// 1. First element of an ordered list
/// 2. Second element of an ordered list
|
表 |
/**
* <table>
* <tr><th>Name</th><th>Role</th></tr>
* <tr><td>John</td><td>Admin</td></tr>
* <tr><td>Jane</td><td>User</td></tr>
* </table>
*/
/// | Name | Role |
/// |------|-------|
/// | John | Admin |
/// | Jane | User |
|
内联代码 |
/**
* Returns a {@code List<String>} with all usernames.
*/
/// Returns a `List<String>` with all usernames.
|
代码块 |
/**
* <pre>{@code
* List<String> names = new ArrayList<>();
* names.add("John");
* names.add("Jane");
* }</pre>
*/
/// ```java
/// List<String> names = new ArrayList<>();
/// names.add("John");
/// names.add("Jane");
/// ```
|
块标记 |
/**
* Calculates prices for items in a shopping list.
*
* @see ShoppingList
* @since 1.0
*/
public class PriceCalculator {
/**
* Applies a discount to the given price.
*
* @param originalPrice the original price
* @param discountPercent the discount percentage
* @return the discounted price
* @throws IllegalArgumentException if the discount percentage is less than 0 or greater than 100
*/
public double applyDiscount(double originalPrice, double discountPercent) { ... }
}
/// Calculates prices for items in a shopping list.
///
/// @see ShoppingList
/// @since 1.0
public class PriceCalculator {
/// Applies a discount to the given price.
///
/// @param originalPrice the original price
/// @param discountPercent the discount percentage
/// @return the discounted price
/// @throws IllegalArgumentException if the discount percentage is less than 0 or greater than 100
public double applyDiscount(double originalPrice, double discountPercent) { ... }
}
|
将传统 Javadoc 注释转换为 Markdown
如果项目使用 Java 23 或更高版本，IntelliJ IDEA 可通过专用快速修复，将代码中的传统 Javadoc 注释快速转换为 Markdown 注释样式。
转换单个 Javadoc 注释
将文本光标置于传统 Javadoc 注释处。
按 Alt+Enter 并选择 转换为 Markdown 文档注释。
转换文件中的所有 Javadoc 注释
将文本光标置于传统 Javadoc 注释处。
按 Alt+Enter 并将鼠标悬停在 转换为 Markdown 文档注释 快速修复上。
在快速修复右侧，点击
更多操作 并选择 修复文件中的所有“Javadoc 注释可以是 Markdown 文档注释”问题。
转换项目、模块或目录中的所有 Javadoc 注释
通过在选定的 作用域 上运行专用检查并批量应用快速修复，可以一次将多个传统 Javadoc 注释转换为对应的 Markdown 形式。
打开 项目 工具窗口 (Alt+1)。
右键点击项目、模块或目录，然后选择 。
或者，选择项目、模块或目录，然后按 Ctrl+Alt+Shift+I。
在 输入检查名称 弹出窗口中，键入
javadoc markdown并按 Enter。在打开的对话框中，选择要转换 Javadoc 注释的作用域。 还可以配置以下选项：
包含测试源 ：如果要转换 测试源 中的 Javadoc 注释，请选择此选项。
检查 inject 的代码 ：如果要转换 inject 的 Java 代码（例如 README 文件中的字符串文字或代码块）中的 Javadoc 注释，请选择此选项。
文件掩码(s) ：使用此选项将作用域缩小到名称与一个或多个特定模式匹配的文件。 了解详情，请参阅 在特定文件类型中搜索。
有关更多信息，请参阅 指定检测范围对话框。
点击 OK。
IDE 会在 问题 工具窗口中列出匹配的 Javadoc 注释。
右键点击 检查结果 节点并选择 转换为 Markdown 文档注释。
在编辑器中渲染 Javadocs
IntelliJ IDEA 允许在编辑器中渲染 Javadoc 注释。 渲染后的注释更易于阅读，可以点击链接转到引用的 web 页面，并且不会让额外标记重载代码。
要渲染 Javadoc 注释，请在装订区域中点击 
切换渲染视图 （或按 Ctrl+Alt+Q）。 要编辑注释，请点击 
切换渲染视图。
默认渲染 Javadoc 注释
可以配置 IDE，使其始终在编辑器中渲染 Javadoc 注释。
在装订区域中，右键点击
切换渲染视图 （或 切换渲染视图 ），然后选择 渲染所有文档注释。。或者，打开 设置 （Ctrl+Alt+S ），转到 ，然后选择 渲染文档注释。
要编辑已渲染的 Javadoc 注释，请在装订区域中点击 切换渲染视图。
更改已渲染 Javadoc 注释的字体大小
右键点击已渲染的 Javadoc 注释，然后选择 调整外观。
在出现的弹出窗口中，调整 字体大小 滑块。
请注意，渲染后的注释使用与 快速文档弹出窗口相同的字体大小。
生成 Javadoc 参考
IntelliJ IDEA 提供了一个实用工具，可为项目生成 Javadoc 参考。
在主菜单中，前往 。
在打开的对话框中，选择一个范围：您想要生成参考的文件或目录集。
在 输出目录 中，指定生成的文档将放置到的文件夹。
从 可见性级别 列表中选择将在生成的文档中包含的成员可见性级别：
公开 ：仅包含 public 类和成员。 该级别对应于
-publicJavadoc 形参。protected ：仅包含 public 和 protected 类及成员。 该级别对应于
-protectedJavadoc 形参。软件包 ：包含除 private 之外的所有类和成员。 该级别对应于
-packageJavadoc 形参。私有 ：包括所有类和成员。 该级别对应于
-privateJavadoc 形参。
您可以指定语言环境（例如
en_US.UTF-8）、命令行参数以及最大堆大小。 有关所有控件的描述，请参阅 参考。点击 生成 生成参考。
参考：生成 JavaDoc 对话框
生成 JavaDoc 对话框的控件对应于 Javadoc 实用工具的选项和标记。
条目 | 描述 |
|---|---|
JavaDoc 作用域 | 请在此区域指定要生成 Javadoc 的文件、文件夹和包的子集。 这个 scope可以是整个项目、最近修改的文件、当前文件、自定义 scope 等等。 |
包含测试源 | 将测试的文档注释包含在生成的 Javadoc 中。 |
在 -sourcepath 中包含 JDK 和库源 | 如果选中此复选框，则 JDK 和库源路径将传递到 Javadoc 工具。 有关更多信息，请参阅 Javadoc 文档。 |
链接到 JDK 文档（使用 -link 选项） | 如果选择此复选框，对 JDK 类和包的引用将变成链接，这对应于使用 Javadoc 工具的 -link 选项。 只有在 文档路径 选项卡的 SDK 设置中指定了在线文档链接时，此复选框才会启用。 如需更多信息，请参阅 Javadoc 文档。 |
输出目录 | 指定生成的文档将存储的目录的完全合格路径。 手动输入路径，或点击 |
可见性级别 | 指定您要在生成的文档中包含的成员可见性级别：
|
生成层次结构树 | 生成类层次结构。 如果清除此复选框，则会将 |
生成导航栏 | 生成导航栏。 如果清除此复选框，则会将 |
生成索引 | 生成文档索引。 如果清除此复选框，则会将 |
每个字母单独的索引 | 为每个字母生成一个单独的索引文件。 如果清除此复选框，则会将 仅当选中 生成索引 复选框时，此复选框才可用。 |
@使用 | 请记录 class 和 package 的使用情况。 选中后，复选框将对应 |
@author | 包含 |
@version | 包含 |
@deprecated | 请包含 |
弃用列表 | 生成过时列表。 当复选框被清除时， 仅当选中 @deprecated 复选框时，此复选框才可用。 |
语言区域 | 输入所需的区域设置。 |
命令行参数 | 输入要传递给 Javadoc 的附加参数。 请使用命令行语法。 |
最大堆大小 | 请输入 Java 虚拟机运行 Javadoc 使用的最大堆大小（以 Mb 为单位）。 |
生成文档并用浏览器打开 | 自动在浏览器中打开生成的 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来允许该标签。 从 Javadoc 文档详细了解 Javadocs 中的块标记。按照 生成 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 工具窗口。
根据要为哪些库下载 Javadoc，执行以下操作之一：
所有已链接 Maven 项目中的所有库：在工具栏中，选择
下载源代码和/或文档 | 下载文档。
特定 Maven 项目中的所有库：右键点击项目的 依赖项 节点，然后选择
下载文档。
特定库：选择一个依赖项（或在选择多个依赖项时按住 Ctrl ），右键点击它，然后选择
下载文档。
打开构建文件（ build.gradle 或 build.gradle.kts ）。
添加 IDEA 插件 ，并将其配置为自动下载缺失的 Javadoc：
plugins { id 'idea' } idea { module { downloadJavadoc = true } }plugins { idea } idea { module { isDownloadJavadoc = true } }按 Ctrl+Shift+O 同步项目。
打开 项目结构 对话框（Ctrl+Alt+Shift+S ），然后选择 库。
选择所需的库，然后点击对话框右侧区域中的 编辑。
在打开的对话框中，选择 下载 Javadocs 并点击 OK。
应用更改并关闭对话框。
手动添加库 Javadoc
可以通过指定 URL 或导入包含 Javadoc 的 JAR 文件，手动添加库的 Javadoc。
指定 Javadocs URL
打开 项目结构 对话框（Ctrl+Alt+Shift+S ），然后转到 库。
从列表中选择一个库，然后点击对话框右侧区域中的
指定文档 URL。在打开的对话框中，输入 Javadoc 站点的根 URL，然后点击 OK。
应用更改并关闭对话框。
添加包含 Javadocs 的 JAR 文件
打开 项目结构 对话框（Ctrl+Alt+Shift+S ），然后转到 库。
从列表中选择一个库，然后点击对话框右侧区域中的
添加。 
在打开的对话框中，选择包含文档的 JAR 文件，然后点击 打开。
应用更改并关闭对话框。
排除 Javadoc 问题
Javadoc 检查问题
如果方法签名已更改，IntelliJ IDEA 会高亮显示与方法签名不匹配的标记，并建议快速修复。
使用上下文操作修复
将文本光标放置在标记处，按 Alt+Enter ，然后选择一个操作。 您可以更改标签或将其删除。
使用 修复文档注释 操作修复
将文本光标放在该标记处，然后按 Ctrl+Shift+A。
输入
修复文档注释并按 Enter。
Javadoc 生成错误
如果 IntelliJ IDEA 在 生成 Javadoc 参考 时遇到任何错误，会在 运行 工具窗口（Alt+4 ）中显示错误详细信息。
修复由 UTF-8 编码导致的格式错误的区域设置名称
如果遇到 javadoc: error – Malformed locale name: en_US.UTF-8 ，请尝试将 UTF-8 编码移到命令行实参中：
在主菜单中，前往 。
清除 语言区域 字段。
在 命令行参数 字段中，输入
-encoding utf8 -docencoding utf8 -charset utf8。-encoding：源文件中使用的编码。-docencoding：输出 HTML 文件中应使用的编码。-charset：Javadoc 应插入到每个输出文件的 HTML head 部分中的字符集。
重新生成 Javadoc 参考。