给thrift的C++添加注释功能

一、thrift注释功能

thrift是有给生成的代码添加注释功能的，但并不支持C++。格式如下：

/**这里写注释*/

/**工具类型，分为定位器和普通*/
enum ToolType
{
    /**检查工具*/
    Check = 0;      
    /**定位器*/
    Fixture = 1;    
    /**通讯工具*/
    IORegex = 2;    
}

或者这样给函数增加注释

/**客户端服务接口*/
service ClientService
{
    /**设置执行结果*/
    bool SetResult(
    /**图片*/
    1: Base.image img,
    /**task列表*/
    2: list<ToolInterface.Task> tasks
    )
}

注释只对它的下一行生效，例如这样就不行：

/**错误的注释格式*/
/**工具类型，分为定位器和普通*/
enum ToolType
{
    Check = 0;      /**检查工具*/
    Fixture = 1;    /**定位器*/
    IORegex = 2;    /**通讯工具*/
}

二、改造thrift，使生成代码时把注释也生成进去。

改造文件”compiler\cpp\src\thrift\generate\t_cpp_generator.cc”，新增对doctext项的处理。

• 501行的generate_typedef函数改为:

void t_cpp_generator::generate_typedef(t_typedef* ttypedef) {
**以下是新增内容
    if (ttypedef->has_doc())
        f_types_ << indent() << "//" << ttypedef->get_doc();
**以上是新增内容
  f_types_ << indent() << "typedef " << type_name(ttypedef->get_type(), true) << " "
           << ttypedef->get_symbolic() << ";" << endl << endl;
}

• 521行新增

if (first) {
      first = false;
    } else {
      f << "," << endl;
    }
**以下是新增内容
if (strlen(prefix) == 0)
    {
        if ((*c_iter)->has_doc())
            indent(f) << "//" << (*c_iter)->get_doc();
    }
**以上是新增内容
indent(f) << prefix << (*c_iter)->get_name() << suffix;

• 544行新增

if (!gen_pure_enums_) {
    enum_name = "type";
    **以下是新增内容
    if (tenum->has_doc())
        f_types_ << indent() << "//" << tenum->get_doc();
    **以上是新增内容
    f_types_ << indent() << "struct " << tenum->get_name() << " {" << endl;
    indent_up();
  }

• 1029行新增

  out << endl;
  **以下是新增内容
  if (tstruct->has_doc())
      out << indent() << "//" << tstruct->get_doc();
  **以上是新增内容
  // Open struct def

• 1101行的整个for循环改为：

  for (m_iter = members.begin(); m_iter != members.end(); ++m_iter) {
    indent(out) << declare_field(*m_iter,
                                 false,
                                 (pointers && !(*m_iter)->get_type()->is_xception()),
                                 !read) << endl;
  }

• 2181行新增:

  for (f_iter = functions.begin(); f_iter != functions.end(); ++f_iter) {
  **以下是新增内容
      generate_java_doc(f_header_, *f_iter);
  **以上是新增内容
    t_struct* arglist = (*f_iter)->get_arglist();

• 2273行新增

  if (tservice->has_doc())
      f_header_ << "//" << tservice->get_doc();

• 2383行新增

generate_java_doc(f_header_, *f_iter);

要改的地方有点多，因为他们分别是处理不同的field

三、编译compiler

打开解决方案”compiler\cpp\compiler.sln”，编译为thrift.exe
并使用thrift.exe来生成cpp代码文件。

四、效果

五、浅谈thrift的语法分析

compiler\cpp\src\thrift\thriftl.ll文件里定义了语法分析的一些配置。在其115行里开始：

intconstant   ([+-]?[0-9]+)
hexconstant   ([+-]?"0x"[0-9A-Fa-f]+)
dubconstant   ([+-]?[0-9]*(\.[0-9]+)?([eE][+-]?[0-9]+)?)
identifier    ([a-zA-Z_](\.[a-zA-Z_0-9]|[a-zA-Z_0-9])*)
whitespace    ([ \t\r\n]*)
sillycomm     ("/*""*"*"*/")
multicm_begin ("/*")
doctext_begin ("/**")
comment       ("//"[^\n]*)
unixcomment   ("#"[^\n]*)
symbol        ([:;\,\{\}\(\)\=<>\[\]])
literal_begin (['\"])

可以看到”/**”被定义为”doctext_begin”，而doctext就是注释了。
简单来讲就是thrift的语法分析用了第三方工具(GNU bison)，而这个库是能够分析出注释的，还能分析出更多的东西。只是thrift的代码生成器(compiler)没有使用这些特性罢了。