IDEA 生成类和方法注释

IDEA 可以自动生成 Javadoc 格式的注释。

快速补全注释

IntelliJ IDEA 提供了自动补全文档格式注释的方法。只要在声明语句的前面打上 /** 然后按下回车,IDE 就会自动给你补全注释。对于方法的注释,产生的注释片段会包含所需要的标签(每个参数的 @param 标签、@return@throws等等)。

IDEA 的文档注释补全

文档格式的注释也支持 JavaScript、Python、Ruby、和 PHP。

使用 Fix doc comment 动作

  1. 把光标放在一段类,方法,函数或者成员变量中,然后按下 Ctrl+Shift+A

  2. 打上 fix doc comment 然后按下回车。

IDEA 就会自动给注释增加上缺失部分的标签。

fix doc comment 动作 | IDEA 帮助文档

如果一个方法的特征改变了,IDEA会高亮出不匹配部分的标签,然后提出快速修改的建议。

标签的自动补全

对于文档注释的标签,IDEA 也提供了代码自动补全。在 @ 标记的后面按下 Ctrl+Space ,然后就能够从弹出建议的列表里面选择需要的标签了。如果标签包含多个值(比如 @param),可以在建议的列表里面继续选择。

标签的补全 | IDEA 帮助文档

但是 Ctrl+Space 在微软拼音输入法里面是切换中英文的快捷方式,造成冲突而且不能改变……你可以添加一个英语语言,然后按 Win+Space切换到英语键盘来编码。

有什么好处

你一定查过 Java 的 API 文档。这份文档是怎么制作的呢?没错,用的就是 Javadoc 格式的注释。查看 JDK 的源码,你就能发现这种格式的注释。只要我们按照这种规范来编写注释,就能使用 javadoc 工具从代码生成 HTML 文档。

(文档和代码的耦合性这么高,难道这就是 Java 一直没有中文文档的原因……)

还有一个好处就是,IDEA 也会识别这种注释。将光标移动到类名或方法名上,按下 Ctrl+Q,就会弹出气泡提示:

IDEA 显示快速文档查看气泡

自动气泡提示

如果要让鼠标移动到类名上自动弹出提示,可以这么做:

File -> Settings.. -> Editor -> General,找到项目 Show quick documentation on mouse move,勾选上就可以了。

设置自动显示气泡提示

参考资料: