如何使用宏提取C++方法的Doxygen注释

嘿，我刚好折腾过类似的需求，先给你泼个小冷水：纯C++宏是没法直接提取已经写好的Doxygen注释的——因为预处理阶段会直接忽略所有注释内容，宏根本“看不到”它们。不过我们可以换个思路，用宏来把注释和函数绑定在一起，间接实现“提取”和复用注释的效果，下面给你几个实用的方案：

方案1：绑定完整Doxygen注释并保存 #

我们可以写一个宏，让你把完整的Doxygen注释作为参数传进去，同时定义函数，还能把注释文本存到全局容器里方便后续使用：

#include <vector>
#include <string>
#include <unordered_map>

// 用来存储函数名和对应Doxygen注释的全局映射
std::unordered_map<std::string, std::string> func_doxygen_db;

#define DEF_FUNC_WITH_FULL_DOXY(DOXY_COMMENT, RET_TYPE, FUNC_NAME, PARAMS, BODY) \
    /* 把注释文本存入全局映射 */ \
    do { \
        func_doxygen_db[#FUNC_NAME] = #DOXY_COMMENT; \
    } while(0) \
    /* 展开注释和函数定义 */ \
    DOXY_COMMENT \
    RET_TYPE FUNC_NAME PARAMS BODY

// 实际使用这个宏
DEFINE_FUNC_WITH_FULL_DOXY(
    /**
     * Given a filename generated by writeVectorToFile, we read it to a vector of Eigen::VectorXd
     *
     * @param[in] filename Path to binary file to read from
     * @return vec A vector of Eigen::VectorXd
     */,
    std::vector<Eigen::VectorXd>,
    readVectorXdFromFile,
    (const std::string &filename),
    {
        std::vector<Eigen::VectorXd> result;
        // 这里写你的文件读取逻辑
        return result;
    }
)

之后你就可以通过func_doxygen_db["readVectorXdFromFile"]拿到这个函数的完整Doxygen注释啦。不过要注意，#DOXY_COMMENT会把注释转成字符串，里面的换行和特殊字符会被预处理自动转义，要是需要格式化输出的话，可能得额外写个小函数处理一下转义字符。

方案2：拆分提取特定注释部分 #

如果你只需要提取@param、@return这类特定字段，可以把这些部分拆成宏的单独参数，这样既能生成规范的Doxygen注释，又能单独复用这些字段内容：

#include <vector>
#include <string>
#include <unordered_map>

// 用来存储特定注释字段的结构体
struct FuncDocInfo {
    std::string brief;
    std::string filename_param;
    std::string return_desc;
};

std::unordered_map<std::string, FuncDocInfo> func_doc_details;

#define DEF_FUNC_WITH_DETAILED_DOXY(BRIEF, PARAM_DESC, RETURN_DESC, RET_TYPE, FUNC_NAME, PARAMS, BODY) \
    do { \
        func_doc_details[#FUNC_NAME] = {BRIEF, PARAM_DESC, RETURN_DESC}; \
    } while(0) \
    /* 自动生成规范的Doxygen注释 */ \
    /** \
     * @brief BRIEF \
     * \
     * @param[in] filename PARAM_DESC \
     * @return RETURN_DESC \
     */ \
    RET_TYPE FUNC_NAME PARAMS BODY

// 使用示例
DEFINE_FUNC_WITH_DETAILED_DOXY(
    "Reads a binary file into a vector of Eigen::VectorXd (generated by writeVectorToFile)",
    "Path to the binary input file",
    "A vector containing the loaded Eigen::VectorXd elements",
    std::vector<Eigen::VectorXd>,
    readVectorXdFromFile,
    (const std::string &filename),
    {
        std::vector<Eigen::VectorXd> result;
        // 读取逻辑
        return result;
    }
)

这种方式的好处是，你可以单独访问func_doc_details["readVectorXdFromFile"].return_desc拿到返回值的描述，不用自己去解析大段注释。

最后提个小限制 #

要注意哦，这些方案都是提前把注释作为宏参数传入来实现的，如果是要处理已经写好的、没有用宏包裹的函数注释，那纯C++宏是做不到的——因为预处理阶段早就把这些注释丢了。这种情况你得用Doxygen自带的工具（比如生成XML输出后解析）或者写个外部脚本（比如Python）来扫描代码文件提取注释。

内容来源于stack exchange