教你如何为你的代码自动生成API文档（文档注释）！

什么是Javadoc

Java中支持 3 种注释，分别是单行注释、多行注释和文档注释。单行注释和多行注释主要用于编写帮助自己理解代码逻辑的文字解释。

文档注释以/**开头，并以*/结束，可以通过 Javadoc 生成 API 帮助文档，Java 帮助文档主要用来说明类、接口、方法、成员变量、构造器和内部类。

Javadoc 是 Sun 公司提供的一种工具，它只处理文档源文件在类、接口、方法、成员变量、构造器和内部类之前的注释，忽略其他地方的文档注释，然后形成一个和源代码配套的 API 帮助文档。也就是说，只要在编写程序时在文档注释中以一套特定的标签注释，在程序编写完成后，通过 Javadoc 就形成了程序的 API 帮助文档。

API 帮助文档相当于产品说明书，而说明书只需要介绍那些供用户使用的部分，所以 Javadoc 默认只提取 public、protected 修饰的部分。如果要提取 private 修饰的部分，需要使用 -private。

简单来说，javadoc就是用于生成帮助文档的，以我之前编写的改变控制台字体颜色的类举个例子。

在目标目录下执行javadoc命令

javadoc -encoding UTF-8 -d doc -author -version Example.java

生成的doc文件

自动生成的api文档
 

如何快速生成简明易懂的文档注释呢？

首先IDEA是自带文档注释自动生成的，使用/**+ENTER就可以自动生成，但实际体验下来并不够灵活，于是作者在网络上寻找，找到了一个简单好用的文档注释生成方法，并在我的实际使用中进行了一些改进。

废话不多说，先贴代码。

param

groovyScript("def result='null.\\n\\t * \\n\\t'; def params=\"${_1}\".replaceAll('[\\\\[|\\\\]|\\\\s]', '').split(',').toList(); for(i = 0; i < params.size(); i++) {if(i == 0 && params[i] == ''){return result;};result+=' * @param ' + params[i] + ((i < params.size() - 1) ? '\\n\\t' : ' ')}; return result", methodParameters())

return

groovyScript("def params=\"${_1}\"; if(params=='void'){return '';} else {return '\\n\\t * @return ' + params}", methodReturnType())

接下来是使用步骤，IDEA版本

将方框中的全部调成如图一致，右下角的下拉框决定了你用什么快捷键生成动态模板。

将上方代码粘贴到对应的位置。

在下图所示这里输入如下文本（注意开头有一行空行），如果想添加其他参数，请按上图所示添加Name并挑选对应的Expression（IDEA提供给你的函数），并在Template Text中以`$Name$`的形式调用。

 * $param$ $return$
 * @author koveer
 * -$date$ $time$
 * @since 1.0        
 */

最后点击右下角蓝色OK就设置成功啦。

使用方法

如果你前面设置正确，那么当你需要使用注释的时候，只需要在方法前输入/***再点击回车（ENTER）

就会出现如下文本，其中null部分是你的代码功能，@param部分是你每个参数的解释。
注意，如果要输入中文，那么你的javadoc命令就必须加上`-encoding UTF-8`

养成良好的代码注释习惯，你的代码再也不会只有上帝知道了！（滑稽）
看到这里了，能麻烦点个赞吗？非常感谢！

参考文章：IDEA 创建类注释模板和方法注释模板 - 简书 (jianshu.com)