IntelliJ IDEA文档注释

IntelliJ IDEA 文档注释

IntelliJ IDEA 为创建文档注释提供了方便的功能。

您的源代码中的文档注释可用于快速文档查找并通过按 Ctrl + Q 打开以进行审阅。

在 Java 文件中，IntelliJ IDEA 在键入打开标签并按下 Enter 键时创建文档注释的存根。

如果此功能适用于方法，则会为方法签名中声明的每个参数创建 @param 标签；@return 如果方法不是无效的，则创建 @return 标签；并为每个异常语句创建 @throws 标签。

当您创建其他标签时，IntelliJ IDEA 提供代码完成，提示可能的标签名称。

如果某个标签具有多个值，则相同的代码完成提供可用值的列表。智能类型代码完成表明适用于特定异常的类的列表。

IntelliJ IDEA 使用 Python 创建文档注释

注意：仅当安装 Python 插件时才支持以下功能！

可以根据在"设置/首选项" 对话框的 "Python 集成工具" 页面中选择的语法创建文档注释，例如：reStructuredText 或 epytext。如果此功能适用于某个函数，则IntelliJ IDEA 将根据所选的文档字符串格式生成标签，例如：

• 对于 reStructuredText：在函数签名中声明的每个参数的 :param 标签和 :return标签。
• 对于 epytext：为在函数签名中声明的每个参数的 @param 标签和 @return 标签。

这样做，会让 reStructuredText 和 epytext 标记中的标签被相应地突出显示。

如果配置，则可以使用 type 和 rtype 标签生成文档注释存根。

在 Python 文件中，IntelliJ IDEA 识别了表示以 Python 文档字符串表示的文档注释。

在开始之前，请确保在 "设置/首选项" 对话框的 "Python 集成工具" 页中选择了所需的文档字符串格式 (例如：epytext 或 reStructuredText)。

另外还要注意，IntelliJ IDEA 从 conf. 中捕获自定义角色。当配置包含 *.rst 文件的目录时，指向带有 conf. 的目录（Python 集成工具| 带有 *. rst 文件的目录的路径）。

注意：只有在安装 Ruby 插件时才支持以下功能！

IntelliJ IDEA 使用 RDoc 创建文档注释

RDoc 标签已完成：

可以启用或禁用文档注释中的 RDoc 突出显示。要启用它，请在编辑器设置的 "外观" 页中选中 "注释中的 RDoc 和 ruby 语法"复选框。

IntelliJ IDEA 使用 YARD 创建文档注释

YARD 标签已完成：

• YARD 指令在可以定义方法的地方完成；
• 类型注释在适用的情况下完成（分配，在块变量之前）；
• param/return/etc. 标签在方法之前完成，内部指令文档字符串，在 attr_reader/writer/accessor 之前。
  

IntelliJ IDEA 使用 HEREDOC 创建文档注释

除了 RDOC 和 YARD 格式的文档注释外，IntelliJ IDEA 还支持 HEREDOCS 格式的文档注释。如果您正在编写大块的文本，这将特别有用。

例如，请考虑以下几点：

Note：IntelliJ IDEA 建议 Ruby 意图行为，将<< - HEREDOC 转换成波形 <<〜HEREDOC。这个意图适用于 Ruby 2.3 及更高版本。

如果您执行运行，<< - HEREDOC 和 HEREDOC 之间的行将出现在 "运行工具" 窗口中。