如何让libclang捕获宏展开后的注释回调？

测试C++代码：

#define SOME_MACRO \
  (void) x; /* some comment in macro */ \

int main()
{
  int x = 0;
  /* some comment in main */
  SOME_MACRO
  SOME_MACRO
  return 0;
}

使用libclang的CommentHandler尝试捕获宏SOME_MACRO展开时的注释，注册代码如下：

struct CommentPrinter : clang::CommentHandler {
  bool HandleComment(Preprocessor & pp, SourceRange comment) {
    llvm::outs() << "new comment : \n";
    comment.dump(pp.getSourceManager());
    return false;
  }
};

struct frontend_t : clang::ASTFrontendAction
{
  std::unique_ptr<clang::ASTConsumer>
    CreateASTConsumer(clang::CompilerInstance& CI,
        clang::StringRef source_file) override
    {
      CI.getPreprocessorOutputOpts().ShowComments = 1;
      CI.getPreprocessorOutputOpts().ShowMacroComments = 1;
      CI.getPreprocessor().addCommentHandler(new CommentPrinter);
      return std::make_unique<ast_consumer_t>();
    }
};

目前CommentHandler只能捕获第2行（宏定义内的注释）和第7行（main函数内的注释），无法捕获第8、9行宏调用展开后的注释，询问是否可以实现捕获宏展开时的注释需求。

要实现每次宏展开都捕获对应注释，仅靠CommentHandler无法完成，需要结合libclang的预处理回调机制调整实现逻辑：

1. 核心原理
   CommentHandler仅在解析源码中直接出现的注释时触发，宏定义中的注释只会在宏定义解析阶段被处理一次，不会在每次宏展开时重复触发回调。要捕获宏展开时的注释，需要监听宏展开事件，主动提取宏定义中的注释内容。

2. 修改实现代码
   结合PPCallbacks监听宏展开时机，同时复用CommentHandler的注释处理逻辑：

struct MacroCommentHandler : clang::PPCallbacks, clang::CommentHandler {
  clang::SourceManager& SM;

  MacroCommentHandler(clang::SourceManager& SM) : SM(SM) {}

  // 处理源码中直接出现的注释
  bool HandleComment(clang::Preprocessor& PP, clang::SourceRange Comment) override {
    llvm::outs() << "Captured comment (direct):\n";
    Comment.dump(SM);
    return false;
  }

  // 监听宏展开事件，提取宏定义中的注释
  void MacroExpands(const clang::Token& MacroNameTok,
                    const clang::MacroDefinition& MD,
                    clang::SourceRange Range,
                    const clang::MacroArgs* Args) override {
    clang::MacroInfo* MacroInfo = MD.getMacroInfo();
    if (!MacroInfo || !MacroInfo->getDefinitionRange().isValid()) {
      return;
    }

    // 获取宏定义的源码范围，用Lexer解析其中的注释
    clang::SourceRange DefRange = MacroInfo->getDefinitionRange();
    clang::Lexer Lex(DefRange.getBegin(), SM.getBufferData(SM.getFileID(DefRange.getBegin())), SM, PP.getLangOpts());
    clang::Token Tok;

    while (!Lex.LexFromRawLexer(Tok)) {
      if (Tok.is(clang::tok::comment)) {
        clang::SourceRange CommentRange(Tok.getLocation(), Tok.getEndLoc());
        llvm::outs() << "Captured comment (macro expand):\n";
        CommentRange.dump(SM);
      }
    }
  }
};

// 在ASTFrontendAction中注册回调
std::unique_ptr<clang::ASTConsumer> CreateASTConsumer(clang::CompilerInstance& CI, clang::StringRef source_file) override {
  CI.getPreprocessorOutputOpts().ShowComments = 1;
  CI.getPreprocessorOutputOpts().ShowMacroComments = 1;
  
  auto* Handler = new MacroCommentHandler(CI.getSourceManager());
  CI.getPreprocessor().addCommentHandler(Handler);
  // 注册PPCallbacks时转移所有权，避免内存泄漏
  CI.getPreprocessor().addPPCallbacks(std::unique_ptr<clang::PPCallbacks>(Handler));
  
  return std::make_unique<ast_consumer_t>();
}

3. 关键说明

• 使用PPCallbacks::MacroExpands回调监听每次宏展开动作，确保每次调用宏时都能触发注释提取逻辑。
• 借助Lexer解析宏定义源码中的注释节点，比字符串匹配更严谨，能正确识别各种格式的注释。
• 注意内存管理：MacroCommentHandler同时继承两个接口，注册时通过unique_ptr转移PPCallbacks的所有权，避免重复释放。

内容的提问来源于stack exchange，提问作者Dorian