效果

注释前代码示例：

public class ContactDto { /** id */ private Long id; /** 联系人姓名 */ private String contactName; public ContactDto() {} public ContactDto(Long id, String contactName) { this.id = id; this.contactName = contactName; } public Long getId() { return id; } public void setId(Long id) { this.id = id; } public String getContactName() { return contactName; } public void setContactName(String contactName) { this.contactName = contactName; } }

自动生成后：

package com.ssp.middle.demo.dto; public class ContactDto { /** id */ private Long id; /** 联系人姓名 */ private String contactName; /** * 实例化一个新的ContactDto。 */ public ContactDto() {} /** * 实例化一个新的ContactDto。 * * @param id id * @param contactName 联系人姓名 */ public ContactDto(Long id, String contactName) { this.id = id; this.contactName = contactName; } /** * 获取id。 * * @return id */ public Long getId() { return id; } /** * 设置id。 * * @param id id */ public void setId(Long id) { this.id = id; } /** * 获取联系人姓名。 * * @return 联系人姓名 */ public String getContactName() { return contactName; } /** * 设置联系人姓名。 * * @param contactName 联系人姓名 */ public void setContactName(String contactName) { this.contactName = contactName; } }

方法

步骤

下载安装IDEA的JavaDoc插件。打开选项：File - Settings - Tools - JavaDocGeneral选项卡： 我不想让自动生成的注释覆盖手动添加的注释，因此把Mode改成Update old javadoc。我的目的是给字段和方法加注释，因此勾选Level中的Method（方法）和Field（字段），取消勾选Type（类/接口/枚举）。我想给所有元素（包括私有）加注释，所以勾选Visibility中的全部4个。Other里面我是全勾选的，不过应该没有影响。 Templates选项卡设置模板，见下文。

模板

Class Level

这里可以设置类/接口/枚举的注释模板，我这里没有使用（而且之前也取消勾选了）。

Constructor Level

这里设置的是类和枚举的构造函数注释模板。默认的模板我不用，因此我删掉了，写了一个对所有构造函数生效的模板：

匹配正则表达式：.+

/**\n * <#if element.parent.isEnum()>定义<#else>实例化</#if>一个新的${element.name}。\n <#if element.parameterList.parameters?has_content> *\n </#if><#list element.parameterList.parameters as parameter> * @param ${parameter.name} <#if element.getParent().findFieldByName(parameter.name,true)?? & element.getParent().findFieldByName(parameter.name,true).getDocComment()?? >${element.getParent().findFieldByName(parameter.name,true).getDocComment().getDescriptionElements()[1].getText()?trim}<#else>${parameter.name}</#if>\n </#list><#if element.throwsList.referenceElements?has_content> *\n </#if><#list element.throwsList.referenceElements as exception> * @throws ${exception.referenceName} the ${exceptionNames[exception.referenceName]}\n </#list> */

Method Level

这里设置方法的注释模板。自带的四个模板分别是：getter，setter，main方法和所有方法。我这里不用后两个，因此直接删了；getter和setter方法做了修改。

Getter方法

我只想给不带参数的getXxx方法加注释，因此修改了正则表达式最后的\(.*\).+，改为了\(\s*\).+。即：

匹配正则表达式：^.*(public|protected|private)*\s*.*(\w(\s*<.+>)*)+\s+get\w+\s*\(\s*\).+

模板：

/**\n * 获取<#if element.getParent().findFieldByName(fieldName,true)?? & element.getParent().findFieldByName(fieldName,true).getDocComment()?? >${element.getParent().findFieldByName(fieldName,true).getDocComment().getDescriptionElements()[1].getText()?trim}<#else>${fieldName}</#if>。\n <#if element.typeParameters?has_content> * \n </#if><#list element.typeParameters as typeParameter> * @param <${typeParameter.name}> \n </#list><#if element.parameterList.parameters?has_content> *\n </#if><#list element.parameterList.parameters as parameter> * @param ${parameter.name} <#if element.getParent().findFieldByName(parameter.name,true)?? & element.getParent().findFieldByName(parameter.name,true).getDocComment()?? >${element.getParent().findFieldByName(parameter.name,true).getDocComment().getDescriptionElements()[1].getText()?trim}<#else>${parameter.name}</#if>\n </#list><#if isNotVoid> *\n * @return <#if element.getParent().findFieldByName(fieldName,true)?? & element.getParent().findFieldByName(fieldName,true).getDocComment()?? >${element.getParent().findFieldByName(fieldName,true).getDocComment().getDescriptionElements()[1].getText()?trim}<#else>${fieldName}</#if>\n </#if><#if element.throwsList.referenceElements?has_content> *\n </#if><#list element.throwsList.referenceElements as exception> * @throws ${exception.referenceName}\n </#list> */

这个模板和Setter保持了一致（除了“获取”和“设置”两个字）。

Setter方法

与Getter类似，我修改了一下正则表达式，限定了参数个数为一个：

匹配正则表达式：^.*(public|protected|private)*\s*.*(void|\w(\s*<.+>)*)+\s+set\w+\s*\(\S+\s+\S+\).+

模板和Getter一样，除了“获取”二字改成“设置”。

toString方法

另外我还单独添加领toString方法的模板。

匹配正则表达式：^.*public\s+String\s+toString\s*\(\s*\).*

/** \n * 转为字符串。\n * \n * @return 字符串\n */

Field Level

默认的字段注释模板是把字段名的每个单词拆开。我直接把所有字段注释模板改成了字段名：

/** ${element.getName()} */

原理

简单来说，就是${element}就是IDEA的插件开发SDK中的PsiElement对象，可以从这里开始顺着文档树，通过字段名找到字段的JavaDoc注释。