【IDEA教程】详解 IDEA Javadocs
Javadoc 是一种从 Java 源代码生成 HTML 格式的 Java 代码文档的工具。文档由 Javadoc 注释组成，这些注释通常位于类、方法或字段之上。
文档注释也可用于JavaScript、Python、Ruby、PHP和Kotlin。
使用自动注释添加 Javadoc
对于文档注释，IntelliJ IDEA 提供默认启用的完成。
- 在声明前输入
/**并按Enter。IDE 会自动为您完成文档注释。
使用上下文操作添加 Javadoc
- 将插入符号放在编辑器中的声明处，按，然后从列表中Alt+Enter选择Add Javadoc 。
对于方法注释，新的注释存根包含必需的标记（
@param每个方法参数的标记@return、 或@throws）。
在 Kotlin 中，@param不会生成 the 和其他标签，因为推荐的样式需要将参数和返回值的描述直接合并到文档注释中。
禁用自动评论
- 在Settings/Preferences对话框Ctrl+Alt+S中，转到Editor | 一般 | Smart Keys，并清除插入文档注释存根复选框。
修复 Javadoc
如果方法签名已更改，IntelliJ IDEA 会突出显示与方法签名不匹配的标记并建议快速修复。按Alt+Enter以应用修复。
您还可以使用Fix doc comment 操作更新现有的 javadoc 注释以说明声明中的更改：
- 将插入符号放在类、方法、函数或字段中，然后按Ctrl+Shift+A。
- 键入
fix doc comment并按Enter。
您可以使用Fix doc 注释操作来添加缺少的文档存根以及相应的标签：将插入符号放在类、方法或函数中并调用该操作。
渲染 Javadocs
IntelliJ IDEA 允许您在编辑器中呈现 Javadocs。呈现的注释更易于阅读，并且它们不会用额外的标签使您的代码超载。
单击
必要文档注释旁边的装订线（或按Ctrl+Alt+Q）以切换呈现的视图；单击
以编辑评论。
常规视图
渲染视图
呈现的 Javadocs 允许您单击链接以转到所引用的网页，或查看所引用主题的快速文档。
要更改字体大小，请在编辑器中右键单击 Javadoc，然后从上下文菜单中选择调整字体大小。请注意，呈现的注释使用与快速文档弹出窗口相同的字体大小。
默认呈现 Javadocs
您可以将 IDE 配置为始终在编辑器中呈现 Javadocs。
- 右键单击装订线 (或) 中的图标并启用“全部渲染”选项。
或者，在Settings/Preferences对话框Ctrl+Alt+S中，选择Editor | 一般 | 外观并启用渲染文档注释选项。
要编辑呈现的 Javadocs，请单击注释旁边的装订线中的图标。
生成 Javadoc 参考
IntelliJ IDEA 提供了一个实用程序，使您能够为您的项目生成 Javadoc 引用。
- 从主菜单中，选择工具 | 生成 JavaDoc。
- 在打开的对话框中，选择一个范围——您要为其生成引用的一组文件或目录，并设置将放置生成的文档的输出目录。
输出目录是必填字段：您不能生成 Javadoc 文件，只要它是空的。
使用滑块定义将包含在生成的文档中的成员的可见性级别。选择以下选项之一：
- Private：包含引用的所有类和成员。
- 包：包括除私有类和成员之外的所有类和成员。
- 受保护的：包括公共和受保护的类和成员。
- Public：仅包括公共类和成员。
- 您可以指定语言环境（例如
en_US.UTF-8）、命令行参数和最大堆大小。 - 单击确定以生成参考。
指定生成 JavaDoc 范围对话框
工具| 生成 JavaDoc对话框调用JavaDoc实用程序。对话框的控件对应于该实用程序的选项和标签。
| 物品 | 描述 |
|---|---|
| 生成 Javadoc 范围 | 使用此区域指定应为其生成 JavaDoc 的文件、文件夹和包的子集。此范围可以是整个项目、最近修改的文件、当前文件、自定义范围等。 |
| 包括测试源 | 在生成的 JavaDoc 中包含用于测试的文档注释。 |
| 在 -sourcepath 中包含 JDK 和库源 | 如果选中此复选框，则 JDK 和库源的路径将传递给 JavaDoc 实用程序。 |
| 包含指向 JDK 文档的链接 | 如果选中此复选框，来自 JDK 的类和包的引用将变成链接，这对应于使用 JavaDoc 实用程序的-link选项。只有在SDK设置的“文档路径”选项卡中指定了指向在线文档的链接时，才会启用此复选框。 |
| 输出目录 | 指定将存储生成的文档的目录的完全限定路径。手动键入路径或单击 并在对话框中选择位置。指定的值被传递给-dJavaDoc 实用程序的参数。如果您的系统中不存在指定的目录，系统将提示您创建它。请注意，除非指定了输出目录，否则“确定”按钮将被禁用。 |
| 滑块 | 指定要包含在生成的文档中的成员的可见性级别：Private：选择此级别以包含所有类和成员。该级别对应于-privateJavaDoc 参数。包：选择此级别以包含除私有类和成员之外的所有类和成员。该级别对应于-packageJavaDoc 参数。受保护：选择此级别以仅包含公共和受保护的类和成员。该级别对应于-protectedJavaDoc 参数。公共：选择此级别以仅包含公共类和成员。该级别对应于-publicJavaDoc 参数。 |
| 生成层次树 | 生成类层次结构。如果清除此复选框，则将-notree参数传递给 JavaDoc。 |
| 生成导航栏 | 生成导航栏。如果清除此复选框，则将-nonavbar参数传递给 JavaDoc。 |
| 生成索引 | 生成文档索引。如果清除此复选框，则将-noindex参数传递给 JavaDoc。 |
| 每个字母单独的索引 | 为每个字母生成一个单独的索引文件。如果清除此复选框，则将-splitindex参数传递给 JavaDoc。The checkbox is available only if the Generate index checkbox is selected. |
| @利用 | 记录类和包的使用。选中后，复选框对应于-useJavaDoc 参数。 |
| @作者 | 包括@author段落。选中后，复选框对应于-authorJavaDoc 参数。 |
| @版本 | 包括@version段落。选中后，复选框对应于-versionJavaDoc 参数。 |
| @不推荐使用 | 包括@deprecated信息。当复选框被清除时，-nodeprecated参数被传递给 JavaDoc。 |
| 弃用列表 | 生成弃用列表。当复选框被清除时，-nodeprecatedlist参数被传递给 JavaDoc。The checkbox is available only if the @deprecated checkbox is selected. |
| 语言环境 | 键入所需的语言环境。 |
| 其他命令行参数 | 键入要传递给 JavaDoc 的附加参数。使用命令行语法。 |
| 最大堆大小 (Mb) | 键入 Java VM 用于运行 JavaDoc 的最大堆大小（以 Mb 为单位）。 |
| 在浏览器中打开生成的文档 | 在浏览器中自动打开生成的 JavaDoc。 |
在编辑器中查看 Javadocs
在 IntelliJ IDEA 中，您可以直接从编辑器查看任何符号或方法签名的 Javadocs。为此，请配置库文档路径或将下载的 Javadocs 添加到 IDE。
- 将鼠标悬停在编辑器中所需的符号上。
- 将插入符号放在符号上并按Ctrl+Q（查看 | 快速文档）。
Ctrl+Q再次按下可在文档工具窗口中打开此文档。
疑难解答
javadoc: error - Malformed locale name: en_US.UTF-8清除区域设置字段。在其他命令行参数字段中，添加-encoding utf8 -docencoding utf8 -charset utf8.
-encoding指定源文件的编码。-docencoding指定输出 HTML 文件的编码，并且-charset是在输出文件的 HTML 头部分中指定的字符集。
