IntelliJ IDEA
 
2023.2
快捷方式：Windows
获取 IntelliJ IDEA
  1. 编写和编辑源代码
  2. Java文档

Java文档

最后修改时间：2023 年 10 月 27 日

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

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

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

提示

JavaScript、Python、Ruby、PHP和Kotlin中也提供了文档注释。

添加Java文档

使用自动注释添加 Javadoc

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

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

您可以禁用自动插入 Javadoc 注释：在“设置”对话框中，转到“编辑器”|“Javadoc 注释” 。一般| 智能键，然后清除插入文档注释存根复选框。CtrlAlt0S

使用上下文操作添加 Javadoc

  • 将插入符号放在编辑器中的声明处，按，然后从列表中选择“添加 Javadoc” 。AltEnter

    使用“添加 Javadoc”上下文操作添加 Javadoc

笔记

对于方法注释，新的注释存根包含所需的标签（@param每个方法参数的标签、@return、 或@throws）。

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

提示

有关记录 Kotlin 代码的更多信息，请参阅Kotlin 文档。

修复 Javadoc

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

使用上下文操作修复

  • 将插入符号放在标签上，按，然后选择一个操作。您可以更改标签或删除它。AltEnter

    使用上下文操作修复 Javadoc

使用“修复文档注释”操作进行修复

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

  1. 将插入符号放在类、方法、函数或字段处，然后按。CtrlShift0A

  2. 键入fix doc comment并按。Enter

提示

您可以使用“修复文档注释”操作来添加缺少的文档存根以及相应的标记：将插入符号放在类、方法或函数中并调用该操作。

渲染Java文档

IntelliJ IDEA 允许您在编辑器中呈现 Javadoc。呈现的注释更易于阅读，并且不会使用额外的标签使您的代码超载。

单击切换渲染视图图标必要的文档注释旁边的装订线（或按）以切换渲染视图；点击编辑评论。CtrlAlt0Q切换渲染视图图标

编辑模式下的 Javadoc

呈现的 Javadoc 允许您单击链接转至引用的网页，或查看引用主题的快速文档。

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

默认渲染 Javadocs

您可以将 IDE 配置为始终在编辑器中呈现 Javadoc。

  • 右键单击切换渲染视图图标装订线中的 ( 图标 或切换渲染视图图标) 并启用“全部渲染”选项。

    或者，在“设置”对话框中，选择编辑器 | 一般| 外观并启用渲染文档注释选项。CtrlAlt0S

要编辑呈现的 Javadoc，请单击切换渲染视图图标注释旁边的装订线中的图标。

在 Javadoc 中使用自定义标签

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

识别自定义标签

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

  • 将插入符号放在您的自定义标记处，按，然后选择将“@tagname”添加到自定义标记。AltEnter

    使用上下文操作识别自定义标签

  • 或者，按打开 IDE 设置，选择编辑器 | 检查。在列表中找到Javadoc 声明问题检查，并将您的标签添加到其他 Javadoc 标签列表中。CtrlAlt0S

    识别设置中的自定义标签

在 Javadoc 参考中包含自定义标签

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

  1. 转到工具| 生成 JavaDoc并在命令行参数字段中指定-tag tagname:Xaoptcmf:"taghead"。

    例子：-tag location:a:"Development Location:"

    Xaoptcmf确定允许将标签放置在源代码中的位置。您可以使用a在所有位置允许该标记。从Oracle 文档中了解有关 Javadoc 中的块标记的更多信息。

  2. 配置其他选项，如生成 Javadoc 参考并生成参考指南中所述。

    标签的信息显示在相应的页面上。

    生成自定义标签

生成 Javadoc 参考

IntelliJ IDEA 提供了一个实用程序，使您能够为项目生成 Javadoc 参考。

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

物品

描述

JavaDoc范围

使用此区域指定应为其生成 Javadoc 的文件、文件夹和包的子集。

该范围可以是整个项目、最近修改的文件、当前文件、自定义范围等。

包括测试源

将测试的文档注释包含到生成的 Javadoc 中。

在 -sourcepath 中包含 JDK 和库源

如果选中此复选框，则 JDK 和库源的路径将传递到 Javadoc 实用程序。有关更多信息，请参阅文档。

链接到 JDK 文档（使用 -link 选项）

如果选中此复选框，则对 JDK 中的类和包的引用将变成链接，这相当于使用Javadoc 实用程序的-link选项。

仅当在SDK设置的“文档路径”选项卡中指定了在线文档的链接时，才会启用此复选框。

有关更多信息，请参阅Javadoc文档。

输出目录

指定将存储生成的文档的目录的完全限定路径。手动键入路径或单击浏览按钮并在对话框中选择位置。指定的值将传递给-dJavadoc 实用程序的参数。如果系统中不存在指定的目录，系统将提示您创建它。

笔记

请注意，除非指定输出目录，否则“确定”按钮将被禁用。

能见度等级

指定要包含在生成的文档中的成员的可见性级别：

  • Private：包括所有类和成员。该级别对应于-privateJavadoc 参数。

  • 包：包括除私有类和成员之外的所有类和成员。该级别对应于-packageJavadoc 参数。

  • Protected：仅包括公共和受保护的类和成员。该级别对应于-protectedJavadoc 参数。

  • Public：仅包括公共类和成员。该级别对应于-publicJavadoc 参数。

生成层次结构树

生成类层次结构。如果清除此复选框，-notree参数将传递到 Javadoc。

生成导航栏

生成导航栏。如果清除此复选框，-nonavbar参数将传递到 Javadoc。

生成索引

生成文档索引。如果清除此复选框，-noindex参数将传递到 Javadoc。

每个字母单独的索引

为每个字母生成一个单独的索引文件。如果清除此复选框，-splitindex参数将传递到 Javadoc。

仅当选中“生成索引”复选框时，该复选框才可用。

@使用

记录类和包的使用。选中后，该复选框对应于-useJavadoc 参数。

@作者

包括@author段落。选中后，该复选框对应于-authorJavadoc 参数。

@版本

包括@version段落。选中后，该复选框对应于-versionJavadoc 参数。

@已弃用

包括@deprecated信息。清除该复选框后，-nodeprecated参数将传递到 Javadoc。

已弃用列表

生成已弃用的列表。清除该复选框后，-nodeprecatedlist参数将传递到 Javadoc。

仅当选中@deprecated复选框时，该复选框才可用。

语言环境

键入所需的区域设置。

命令行参数

键入要传递给 Javadoc 的其他参数。使用命令行语法。

最大堆大小

输入 Java VM 用于运行 Javadoc 的最大堆大小（以 Mb 为单位）。

在浏览器中打开生成的文档

自动在浏览器中打开生成的 Javadoc。

故障排除

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

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

-encoding指定源文件的编码。-docencoding指定输出 HTML 文件的编码，并且-charset是在输出文件的 HTML head 部分中指定的字符集。

参考：Javadoc代码风格

您可以为 Javadoc 配置代码风格。按打开 IDE 设置，然后选择编辑器 | 代码风格| 爪哇 | Java文档。根据需要配置选项并使用对话框的右侧部分预览更改。CtrlAlt0S

从重新格式化代码了解如何重新格式化代码。

物品

描述

结盟

在此区域中，定义 Javadoc 注释的对齐方式。

  • 对齐参数描述：选中此复选框可使参数描述与最长的参数名称对齐。否则，说明与相应的参数名称之间用一个空格分隔。

  • 对齐抛出的异常描述：选择此复选框可将抛出的异常描述与最长的异常名称对齐。否则，描述与异常名称之间用一个空格分隔。

空行

在此区域中，定义应在 Javadoc 注释中插入空行的位置。

  • 描述之后：选择此复选框可在 Javadoc 注释的描述部分之后自动插入一个空行。

  • 参数说明之后：选择此复选框可在标签组之后插入一个空行@param。

  • 返回标签后：选中此复选框可在标签后插入一个空行@return。

无效标签

在此区域中，定义是否应保留无效标签。

  • 保留无效标签：选中此复选框可保留@invalidTag。

  • 保留空 @param 标签：选择此复选框可保留@param不保留描述的标签。

  • 保留空@return 标签：选中此复选框可保留@return不保留描述的标签。

  • 保留空@throws 标签：选择此复选框可保留@throws不保留描述的标签。

其他

在此区域中，指定 Javadoc 注释的附加格式选项。

  • 启用前导星号：Javadoc 注释的每一行都以星号开始。

  • 使用 @throws 而不是 @exception：使用@throws标签。

  • 右边距换行：将超出右边距的文本换行到下一行。

  • 在空行上生成“<p>”：自动</p>在空行上插入标签。

  • 保留空行：选中此复选框可保留手动添加的空行。

  • 不要换行注释：将简短的注释保留在一行上，并带有开始和结束标记。

  • 保留换行符：如果未选中此复选框（默认情况下），则重新格式化时不会保留换行符。当注释应在段落边界内格式化以占用最小空间时，这很方便。

    如果选中此复选框，将保留换行。

  • 参数说明换行：将 Javadoc 参数的说明（如果有）放在新行中。它使用基于连续缩进值的缩进。

  • 缩进连续行：缩进多行注释中的后续行。

生产力技巧

在编辑器中查看 Javadoc

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

  • 将鼠标悬停在编辑器中的必要符号上。

  • 将插入符号放在该符号处，然后按（查看 | 快速文档）。Ctrl0Q

    再次按下可在文档工具窗口中打开此文档。Ctrl0Q

从快速文档中了解更多信息

也可以看看

程序