一、问题描述

安装了阿里代码检测的插件后,敲一个简单的方法,发现提示有问题,如下

/**
 * 查找User的集合
 */
    List<User> findAll();

提示信息为:

方法【findAll】的返回值缺少javadoc注释

进一步查看完整文档里面关于方法注释的规范为

所有的抽象方法(包括接口中的方法)必须要用javadoc注释、除了返回值、参数、异常说明外,还必须指出该方法做什么事情,实现什么功能。 说明:如有实现和调用注意事项,请一并说明。
    /**
     * fetch data by rule id
     * 
     * @param ruleId rule id
     * @param page page number
     * @param jsonContext json format context
     * @return Result<XxxxDO>
     */
    Result<XxxxDO> fetchDataByRuleId(Long ruleId, Integer page, String jsonContext);

二、问题分析

从阿里提供的代码规范我们可以知道以下信息:

  1. 要包含方法说明
  2. 要包含参数列表
  3. 要包含返回值类型
  4. 要严格注意注释的缩进和星号数量

而关于日期、作者、时间这些并没有做要求

所以我们可以通过添加模板的方法,来实现自动注释,避免警告

这里以IDEA为例


三、解决问题

  1. 点击 File - Settings... - Editor - Live Templates
  2. 点击右边的 + 号,选择Template Group...来新建一个模板组
  3. 输入模板组的名称,这里以myJava为例,然后在模板组下点击+Live Template

  1. 注释文本如下,可以直接复制,除了必要的参数列表和返回值后,你还可以自定义方法名、作者、日期等等,这里不再赘述

    **
    * description: 
    $PARAMS$ 
    * @Return $RETURN$
    */
  2. 点击Edit variables,一定要记得把勾都选上,return的值可以在下拉菜单找到,而Params的值请复制以下表达式

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

  1. 点击Apply或者ok,就大功告成了!

四、使用方法

编写完方法后在方法上面输入/*,再TAB就会自动生成模板,然后在第一行输入方法描述就符合规范啦!


注意事项:官方文档中要求@参数需要小写,如果写成了@Return就是错误的,应该写成@return

文章目录