Javadocs

Javadoc 注释通常放置在源代码中的类、方法或字段上方。 Javadoc 提供了位于其下方的代码元素的描述，并包含由 @ 标记的块标签，具有特定的元数据。

您可以使用 JDK 附带的 Javadoc 工具，为您的项目生成 HTML 格式的 API 参考。 IntelliJ IDEA 提供了与该工具的集成，并允许您直接从 IDE 中构建参考指南。

了解有关 Javadocs、样式指南、术语和约定的正确格式的更多信息，请参阅如何为 Javadoc 工具编写文档注释。

渲染 Javadocs

IntelliJ IDEA 允许您在编辑器中渲染 Javadocs。渲染的注释更易于阅读，并且不会因额外的标签而使代码显得杂乱。

点击位于必要的文档注释旁边的装订区域（或按 Ctrl+Alt+Q ）以切换渲染视图；点击以编辑注释。

渲染的 Javadocs 允许您点击链接以访问引用的网页或查看引用主题的快速文档。

要更改字体大小，请右键点击编辑器中的 Javadoc 并从上下文菜单中选择调整字体大小。请注意，渲染的注释使用与快速文档弹出窗口相同的字体大小。

默认渲染 Javadocs

您可以配置 IDE，使其始终在编辑器中渲染 Javadocs。

右键点击（栏中的图标或），启用全部渲染选项。
或者，在设置对话框 Ctrl+Alt+S ，选择编辑器｜常规｜外观并启用渲染文档注释选项。

要编辑呈现的 Javadocs，请点击注释旁边边栏中的图标。

添加 Javadoc 注释

使用自动注释添加 Javadoc

对于文档注释，IntelliJ IDEA 默认启用补全功能。

在声明之前输入 /** 并按 Enter。 IDE 会为您自动完成文档注释。

您可以禁用自动插入 Javadoc 注释：在设置对话框 Ctrl+Alt+S 中，转到编辑器 | 一般 | 智能按键，并清除插入文档注释存根复选框。

使用上下文操作添加 Javadoc 注释

将文本光标置于编辑器中的声明处，按下 Alt+Enter ，并从列表中选择添加Javadoc。

在 Kotlin 中， @param 和其他标签没有生成，因为推荐样式要求将参数和返回值的描述直接并入文档注释中。

格式设置

Javadoc 支持 HTML 标签和用于格式化的特殊标签。了解更多信息，请参阅《如何为 Javadoc 工具编写文档注释》（oracle.com）。

以下是一些 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 描述方法参数。
使用 @deprecated reason 标记方法或类为已弃用。
使用 @author name 指定类的作者。

获取可用标签的完整列表，请参阅《如何为 Javadoc 工具编写文档注释》（oracle.com）。

修复 Javadocs

如果方法签名已更改，IntelliJ IDEA 会突出显示与方法签名不匹配的标签，并建议快速修复。

使用上下文操作修复

将文本光标放置在标记处，按 Alt+Enter ，然后选择一个操作。您可以更改标签或将其删除。

使用修复文档注释操作修复

您还可以使用修复文档注释操作更新现有的 Javadoc 注释，以说明声明中的更改：

将光标放置在类、方法、函数或字段上，然后按 Ctrl+Shift+A。
输入 fix doc comment 并按 Enter。

在 Javadocs 中使用自定义标签

在 Javadocs 注释中，您可以在预定义标签的基础上使用自定义标签。稍后您可以将它们包含在您的 API 参考指南中。

识别自定义标签

当您第一次使用自定义标签时， Javadoc 声明问题检查会在编辑器中将其突出显示为错误标签。为避免这种情况，请将标签添加到已识别标签列表中。

将文本光标放在您的自定义标签处，按 Alt+Enter 并选择将“@tagname”添加到自定义标签。
或者，按 Ctrl+Alt+S 打开 IDE 设置，选择编辑器 | 检查。在列表中找到 Javadoc 声明问题检查，并将您的标签添加到 Additional Javadoc tags 列表中。

将自定义标签包含在 Javadoc 引用中

要在 HTML Javadoc 引用中包含您的自定义标签，请将它们作为命令行参数添加。

请转到工具 | 生成JavaDoc 并在命令行实参字段中指定 -tag tagname:Xaoptcmf:"taghead"。
示例： -tag location:a:"Development Location:"
Xaoptcmf 决定标签在源代码中允许放置的位置。您可以在所有地方使用 a 来允许该标签。了解更多有关 Javadocs 中块标签的信息，请参阅 Oracle 文档。
按照生成 Javadoc 参考中描述的配置其他选项，并生成参考指南。
标签中的信息显示在对应的页面上。

生成 Javadoc 参考

IntelliJ IDEA 提供了一种实用工具，能够为您的项目生成 Javadoc 参考。

在主菜单中，前往工具 | 生成JavaDoc。
在打开的对话框中，选择一个范围：您想要生成参考的文件或目录集。
在输出目录(D) 中，指定生成的文档将放置的文件夹。
输出目录(D) 是必填字段：只要它为空，就无法生成 Javadoc 文件。
从可见性级别列表中选择将在生成的文档中包含的成员可见性级别：
- 私有(I) ：包括所有类和成员。该级别对应 -private Javadoc 参数。
- 软件包：包括所有的类和成员，除了私有的那些。该级别对应 -package Javadoc 参数。
- protected(T) ：仅包含 public 和 protected 类及成员。该级别对应 -protected Javadoc 参数。
- public(B) ：仅包含公共类和成员。该级别对应 -public Javadoc 参数。
您可以指定语言环境（例如 en_US.UTF-8 ）、命令行参数以及最大堆大小。
点击生成生成参考。

指定生成 JavaDoc 范围对话框

工具 | 生成JavaDoc 对话框调用 Javadoc工具。对话框控件对应该工具的选项和标签。

条目	描述
JavaDoc 作用域	请在此区域指定要生成 Javadoc 的文件、文件夹和包的子集。这个 scope可以是整个项目、最近修改的文件、当前文件、自定义 scope 等等。
包含测试代码(T)	将测试的文档注释包含在生成的 Javadoc 中。
在-sourcepath 中包含 JDK 和库源	如果选中此复选框，则 JDK 和库源路径将传递到 Javadoc 工具。如需更多信息，请参阅文档。
链接到JDK 文档 (使用 -link 选项)	如果选择此复选框，对 JDK 类和包的引用将变成链接，这对应于使用 Javadoc 工具的 -link 选项。只有在文档路径选项卡的 SDK 设置中指定了在线文档链接时，此复选框才会启用。如需更多信息，请参阅 Javadoc 文档。
输出目录(D)	指定生成的文档将存储的目录的完全合格路径。请手动输入路径或点击并在对话框中选择位置。指定的值被传递给 Javadoc 实用工具的 `-d` 参数。如果您的系统中未存在指定目录，您将被提示创建该目录。请注意，除非指定了输出目录，否则 OK 按钮将被禁用。
可见性级别	指定您要在生成的文档中包含的成员可见性级别：私有(I) ：包括所有类和成员。该级别对应 `-private` Javadoc 参数。软件包：包括所有的类和成员，除了私有的那些。该级别对应 `-package` Javadoc 参数。 protected(T) ：仅包含 public 和 protected 类及成员。该级别对应 `-protected` Javadoc 参数。 public(B) ：仅包含公共类和成员。该级别对应 `-public` Javadoc 参数。
生成层次结构树	生成类层次结构。如果此复选框被清除， `-notree` 参数将传递给 Javadoc。
生成导航栏	生成导航栏。如果此复选框被清除， `-nonavbar` 参数将传递给 Javadoc。
生成索引	生成文档索引。如果此复选框被清除， `-noindex` 参数将传递给 Javadoc。
每个字母单独的索引	为每个字母生成一个单独的索引文件。如果此复选框被清除， `-splitindex` 参数将传递给 Javadoc。仅当选中生成索引复选框时，此复选框才可用。
@使用	请记录 class 和 package 的使用情况。选中后，复选框将对应 `-use` Javadoc 参数。
@author	包括 `@author` 段落。选中时，此复选框对应于 `-author` Javadoc 参数。
@version	包括 `@version` 段落。选中时，此复选框对应于 `-version` Javadoc 参数。
@deprecated	请包含 `@deprecated` 信息。复选框被清除时， `-nodeprecated` 参数会传递给 Javadoc。
弃用列表	生成过时列表。当复选框被清除时， `-nodeprecatedlist` 参数会传递给 Javadoc。仅当选中 @deprecated 复选框时，此复选框才可用。
区域设置(L)	输入所需的区域设置。
命令行实参	输入要传递给 Javadoc 的附加参数。请使用命令行语法。
堆大小上限(M)	请输入 Java 虚拟机运行 Javadoc 使用的最大堆大小（以 Mb 为单位）。
生成文档并用浏览器打开(G)	自动在浏览器中打开生成的 Javadoc。

故障排除

javadoc: error – Malformed locale name: en_US.UTF-8

清除区域设置(L) 字段。在其他命令行实参字段中，添加 -encoding utf8 -docencoding utf8 -charset utf8。

-encoding 指定了源文件的编码。 -docencoding 指定输出 HTML 文件的编码， -charset 是输出文件 HTML 头部指定的字符集。

参考：Javadoc 代码样式

您可以配置 Javadocs 的代码样式。按 Ctrl+Alt+S 打开设置，然后选择编辑器 | 代码风格 | Java | Javadocs。根据需要配置选项，并使用对话框的右侧部分预览更改。

了解如何从重新设置代码格式重新格式化您的代码。

条目	描述
对齐	定义 Javadoc 注释的对齐方式。对齐形参说明：将参数说明与最长的参数名称对齐。否则，描述与相应的参数名称之间以单个空格分隔。对齐抛出异常说明：将抛出异常的描述与最长的异常名称对齐。否则，描述与异常名称之间由一个空格分隔。
空行	定义在 Javadoc 注释中应插入空白行的位置。在描述后：在 Javadoc 注释的描述部分之后自动插入一个空行。在形参描述后：在 `@param` 标签组后自动插入一个空行。在return后：在 `@return` 标签之后自动插入一个空行。
无效标签	在此区域内，定义是否应保留无效的选项卡。保持无效标签：保留 `@invalidTag`。保持空@param 标签：保留没有描述的 `@param` 标签。保持空@return 标签：保留没有描述的 `@return` 标签。保持空@throws 标签：保留没有描述的 `@throws` 标签。
其他	在此区域中，为 Javadoc 注释指定附加格式化选项。启用前导星号：每行 Javadoc 注释都应以星号开头。用@throws 而不是 @exception ：使用 `@throws` 选项卡。在右页边距处换行：将超出右边距的文本换行到下一行。在空行中生成"<p>" ：在空行上自动插入 `</p>` 选项卡。保留空行：选中此复选框以保留手动添加的空行。一行注释不分行：请将简短的注释保持在一行中，并与开头和结尾的选项卡一起使用。保留换行：如果未选中此复选框（默认情况下），在重新格式化时不会保留换行符。当需要将注释格式化在段落的边界内，以占用最小的空间时，这是非常方便的。如果选中此复选框，将保留换行符。形参描述在新行：将 Javadoc 参数的描述（如果有）放到新的一行。它根据续行缩进值进行缩进。缩进连续线：在多行注释中缩进后续行。

效率提示

在编辑器中查看 Javadocs

在 IntelliJ IDEA 中，您可以直接从编辑器查看任何符号或方法签名的外部 Javadocs。要实现此目的，配置库文档路径或将下载的文档添加到 IDE。

在编辑器中将鼠标悬停在所需符号上。
将插入符号放在符号处，然后按 Ctrl+Q （视图 | 快速文档）。
再次按下 Ctrl+Q 键，以在文档工具窗口中打开此文档。

了解更多信息，请访问快速文档

最后修改日期： 2025年 4月 24日