IntelliJ IDEA如何创建文档注释

2018-10-20 10:58 更新

IntelliJ IDEA 创建文档注释

请注意:本节引用了 JavaScript、Java、Python 和其他具有特殊文档注释开头的语言。本节不引用 Ruby。

IntelliJ IDEA 可以使用专用的操作创建文档注释和修复文档注释,可以通过 "查找操作" 命令调用它。

按 Ctrl+Shift+A,将插入符号放在类、方法、函数或字段中的某个位置,字符应被记录,并输入操作名称修复文档字符串。添加了相应标签的缺少文档存根。例如:

/**
*
* @param userInput
* @return
*/
static boolean processRepeatConversion (@NotNull String userInput) {
boolean repeatConversion = false;
if (((userInput.equals("y")) || (userInput.equals("Y")))) {
repeatConversion = true;
}
return repeatConversion;

}

IntelliJ IDEA 修复文档注释

接下来的示例说明了现有文档注释中的修复问题。

下一个案例在现有文件评论中出现了修复问题。

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

tip:修复文档注释的操作没有键盘快捷键,但是您可以配置你自己的键盘快捷方式。

对于 JavaScript,IntelliJ IDEA 建议一个意图行为 UpdateJSDoc 评论。您也可以按 Ctrl+Shift+A,然后键入操作名称:

IntelliJ IDEA 修复文档注释

IntelliJ IDEA 为方法和函数创建文档注释

在 IntelliJ IDEA 中可以为方法或函数创建文档注释,具体的操作步骤如下所述:

  1. 在声明前放置插入符号。
  2. 键入开启块注释/**,然后按 Enter 键。
  3. 添加有意义的参数描述和返回值。

在您使用 IntelliJ IDEA 为方法和函数创建文档注释的时候,请您注意以下事项:

  • IntelliJ IDEA 会检查文档注释中的语法,并根据错误设置对其进行处理。
  • 如果输入的文本包含 HTML 标签,则在键入 > 后将自动添加结束标签,前提是在编辑器设置中启用了此行为。
  • 当在输入文档注释时,插入符号会自动移动到预期的位置。例如:
    IntelliJ IDEA 为方法和函数创建文档注释

IntelliJ IDEA 在文档注释块中创建标签

  1. 在注释块中,选择所需的空行和输入@或 character (对于 Python 和 Ruby 语言)。
  2. 按 Ctrl+Space,或者只是等待代码完成显示建议列表:
    IntelliJ IDEA 在文档注释块中创建标签
  3. 从建议列表中选择一个标签。例如,您可以指定参数类型或返回类型。
  4. 如果某个标签有多个值,请在标签后按 Ctrl+Space ,然后从建议列表中选择所需的值。例如,IntelliJ IDEA 建议选择所需的参数名称。
    IntelliJ IDEA 在文档注释块中创建标签
注意:以下仅在安装并启用 Ruby Plugin 时有效!

IntelliJ IDEA 为 Ruby 方法创建文档注释

  1. 将插入符号放在要记录的方法声明之前的空行上
  2. 键入文档注释的开头(#),或者只是按 Ctrl+Slash。
  3. 按 Ctrl+Space,并从建议列表中选择所需的标签。然后再次按 Ctrl+Space,然后选择所需的参数名称:
    IntelliJ IDEA 为 Ruby 方法创建文档注释

要使用意图行为为 Ruby 方法创建文档注释,请执行以下操作之一:

  • 将插入符放在要记录的方法中的任何位置,按下 Alt+Enter 并选择 "添加 @return 标记"。将创建带有 @return 标记的文档注释。指定返回类型:
    IntelliJ IDEA 为 Ruby 方法创建文档注释
  • 将插入符号放在要记录的参数上,按 Alt+Enter,然后选择 "添加 @param 标签"。将创建带有所选参数的 @param 标签的文档注释。指定参数类型:
以下仅在安装并启用 Python Plugin 时有效!

IntelliJ IDEA 为 Python 函数创建文档注释

您需要注意以下几点:

  • 当在编辑器设置页面的智能键页面中清除了“插入引号对”复选框时,如果按下 Space 键生成的文档字符串会有打开三重引号。

  • 如果重命名一个函数的参数,IntelliJ IDEA 将相应地更新文档注释中的标记。

为 Python 函数创建文档注释的操作步骤如下:

  1. 将插入符号放在要记录的函数声明之后。
  2. 键入 "打开三重号",然后按 Enter,或 Space。
  3. 添加有意义的参数描述和返回值。

使用意图行为为 Python 函数创建文档注释的步骤:

  1. 将插入符号放在要记录的函数中的某个位置。
  2. 按 Alt+Enter 显示可用的意图行为。
  3. 选择插入文档字符串存根:
    IntelliJ IDEA 为 Python 函数创建文档注释

    IntelliJ IDEA 根据 文档字符串格式生成文档注释存根,在 Python 集成工具页面中选择。

使用 Python 注释的例子:

考虑以下功能:

def handle(self, myParam1, myParam2):

在 "Python 集成工具" 页中,选择 "Epytext"。然后键入打开的三重引号,然后按 Enter 或 Space。IntelliJ IDEA 生成文档注释存根:

'''
@param self:
@param myParam1:
@param myParam2:
@return:
'''

然后选择 reStructuredText,键入打开的三重引号,然后按 Enter 或 Space。IntelliJ IDEA 生成文档注释存根:

'''
:param self:
:param myParam1:
:param myParam2:
:return:
'''

IntelliJ IDEA 填充段落

Java 注释 支持“填充段落”操作。此操作会在注释中创建软包装。要使用此操作,请按照下列步骤操作:

  1. 将插入符号放在类中的某个注释内。
  2. 执行以下操作之一:
    • 在主菜单上选择编辑|填充段落。
    • 按下 Ctrl+Shift+A,在弹出框中,键入填充段落,然后按 Enter 键。

IntelliJ IDEA 中可点击的注释

如果文档注释包含超链接,您可以使其可点击。

要做到这一点,请执行以下操作之一:

  • 按住 Ctrl 键并将鼠标指针悬停在超链接上:
    IntelliJ IDEA 中可点击的注释
  • 按 Ctrl+B。


以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号