Thrift IDL 参数注释重复问题及解决方法

在使用Thrift自动生成java文档时遇到一个问题，在IDL中对service下的方法添加参数注释"@param"后，Thrift在生成代码时还会自动生成一份"@param"，导致"@param"出现重复的情况。
之前我一直认为这是Thrift的一个小bug，因为影响并不大，所以也没有太在意。

最近查阅了一下Thrift的源码找出了那段自动生成Java注释的代码(C++)，如下：

/**
 * Emits a JavaDoc comment if the provided function object has a doc in Thrift
 */
void t_javame_generator::generate_java_doc(ofstream &out,
                                         t_function* tfunction) {
  if (tfunction->has_doc()) {
    stringstream ss;
    ss << tfunction->get_doc();
    const vector<t_field*>& fields = tfunction->get_arglist()->get_members();
    vector<t_field*>::const_iterator p_iter;
    for (p_iter = fields.begin(); p_iter != fields.end(); ++p_iter) {
      t_field* p = *p_iter;
      ss << "\n@param " << p->get_name();
      if (p->has_doc()) {
        ss << " " << p->get_doc();
      }
    }
    generate_docstring_comment(out,
      "/**\n",
      " * ", ss.str(),
      " */\n");
  }
}

从这段代码中可以看出，Thrift自动生成Java注释的顺序为：1.引用function级别注释 -> 2.循环添加"@param "和field名 -> 3.如果field有注释，则引用field级别注释。
之前出现"@param"注释重复的问题原因找到了，因为我们按照Java的注释习惯将参数注释添加到了function的注释中而没有添加到field的注释中，在第1步引用function级别注释时就已经加入了"@param"注释，之后再执行第二步又再次添加了"@param"注释，所以在目标代码中的参数注释就重复了。

解决方法

去掉function级别注释中的参数注释，将参数注释添加到对应的参数上。例子如下：

原IDL片段

/**
* 财务核算总表查询
*
* @author sulei
* @param tmcId 所属TMC编号
* @param stasticLengthType 统计周期类型 REAL_TIME:实时结算, DAILY:日期结算, WEEKLY:周结算, MONTHLY:月结算, QUARTERLY:季度结算, HALF_YEARLY:半年结算, YEARLY:年结算
* @param stasticLengthType 统计周期值 与类型对应(例如 年结: "2014", 季结: "2014Q3", 月结: "201410", 周结: "201430", 日结: "20141001")
* @param companyId 公司ID
* @param pageIndex 页码
* @param pageSize 每页显示数
* @return FinanceListResponse 财务核算总表结果集
*/
FinanceListResponse getFinances(
    1: required i32 tmcId, 
    2: string stasticLengthType, 
    3: string stasticLengthValue, 
    4: i32 companyId, 
    5: i32 pageIndex=DEFAULT_PAGE_INDEX, 
    6: i32 pageSize=DEFAULT_PAGE_SIZE),

修改后的IDL片段

/**
* 财务核算总表查询
*
* @author sulei
*
* @return FinanceListResponse 财务核算总表结果集
*/
FinanceListResponse getFinances(
    /** 所属TMC编号 */
    1: required i32 tmcId, 
    /** 统计周期类型 REAL_TIME:实时结算, DAILY:日期结算, WEEKLY:周结算, MONTHLY:月结算, QUARTERLY:季度结算, HALF_YEARLY:半年结算, YEARLY:年结算 */
    2: string stasticLengthType, 
    /** 统计周期值 与类型对应(例如 年结: "2014", 季结: "2014Q3", 月结: "201410", 周结: "201430", 日结: "20141001") */
    3: string stasticLengthValue, 
    /** 公司ID */
    4: i32 companyId, 
    /** 页码 */
    5: i32 pageIndex=DEFAULT_PAGE_INDEX, 
    /** 每页显示数 */
    6: i32 pageSize=DEFAULT_PAGE_SIZE),

 

转载于:https://my.oschina.net/venwyhk/blog/694926