如何将C++头文件注释便捷迁移至Pybind11绑定？

方案1：Doxygen + 自定义脚本自动生成带注释的绑定代码 #

这是最通用的自动化方案，核心思路是用Doxygen提取C++注释为结构化XML格式，再写脚本解析格式并生成带.doc()调用的Pybind11绑定代码。

步骤：

• 配置Doxygen：在Doxyfile中开启GENERATE_XML = YES，确保Doxygen能识别你的头文件注释（比如///或/*! ... */风格）。
• 生成XML文档：执行doxygen Doxyfile，在xml/目录下得到包含所有注释信息的结构化文件。
• 编写Python脚本解析XML：用xml.etree.ElementTree遍历XML节点，提取类、函数的注释文本，自动生成绑定代码片段。

示例脚本片段：

import xml.etree.ElementTree as ET

tree = ET.parse('xml/classMyClass.xml')
root = tree.getroot()

# 提取类注释
class_brief = root.find('./compounddef/briefdescription').text.strip()
class_detail = root.find('./compounddef/detaileddescription').text.strip()
class_doc = f"{class_brief}\n{class_detail}"

# 提取成员函数注释
for member in root.findall('./compounddef/sectiondef/memberdef[@kind="function"]'):
    func_name = member.find('./name').text
    func_brief = member.find('./briefdescription').text.strip()
    func_detail = member.find('./detaileddescription').text.strip()
    func_doc = f"{func_brief}\n{func_detail}"
    
    # 生成Pybind绑定代码
    print(f'.def("{func_name}", &MyClass::{func_name}, "{func_doc}")')

可根据代码结构扩展脚本，比如处理重载函数、参数注释等。

方案2：用宏实现注释复用 #

如果不想引入外部工具，可通过C++宏让注释在头文件和Pybind绑定中复用，避免重复编写。

示例：
在C++头文件中：

/// 加法函数：计算两个整数的和
/// @param a 第一个整数参数
/// @param b 第二个整数参数
/// @return 两数之和
#define ADD_FUNC_DOC "加法函数：计算两个整数的和\n参数:\n  a: 第一个整数参数\n  b: 第二个整数参数\n返回: 两数之和"
int add(int a, int b);

在Pybind绑定代码中：

#include "my_header.h"
#include <pybind11/pybind11.h>

namespace py = pybind11;

PYBIND11_MODULE(my_module, m) {
    m.def("add", &add, ADD_FUNC_DOC);
}

这种方式只需写一次注释，同时支持C++端的文档生成和Pybind端的注释绑定。

方案3：借助pybind11-autogen工具 #

第三方工具pybind11-autogen可自动解析C++头文件，提取Doxygen注释并转换为Pybind的.doc()内容，直接生成带注释的绑定代码框架，你只需根据需求调整细节即可。

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