如何为boost::signals2的函数签名编写规范的Doxygen文档

原有写法的核心问题 #

Doxygen 没有内置对 boost::signals2::signal 模板类型的识别能力，无法自动把模板尖括号内的void(int, double)解析为信号的函数签名，原写法存在几个明显的适配问题：

• 所有说明都是纯文本罗列，没有使用Doxygen可识别的规范标签，生成文档时会把这段内容全部当成普通段落文本，不会单独生成结构化的参数说明区块
• 文本存在拼写错误（doulbe），会直接同步到最终生成的对外文档中
• 没有区分信号的业务功能、参数语义、行为规则，阅读文档的人无法快速理解信号的实际用途

合规编写的核心要点 #

• @brief 模块必须写清楚信号本身的业务作用，不能只罗列变量名
• 由于信号的调用规则和普通函数一致，可以直接复用@param标注信号触发时需要传递的入参、@return标注触发后返回值的语义，不需要特殊的专属标签
• 补充@note说明信号是signals2多播类型的固有特性，避免读者把变量误认为普通函数指针
• 不需要逐行拆解模板参数的类型做说明，模板的固定签名对最终读文档的业务同学没有实际价值

标准写法示例 #

/**
 * @brief 设备在线状态变更时触发的多播信号
 *
 * 所有连接该信号的槽函数都会在状态变更时收到通知，不保证槽函数的执行顺序
 *
 * @param anInteger 触发信号时传入的设备ID枚举值
 * @param aDouble 触发信号时传入的设备状态更新时间戳（双精度浮点，单位秒）
 * @return 默认配置下返回最后一个执行的槽函数的返回值，无特殊业务约束
 */
boost::signals2::signal<void(int,double)> aSignal;

实操优化技巧 #

• 如果项目中大量定义signals2信号，可以在Doxygen配置文件中添加自定义别名，将信号参数标注简化为专属标签，减少重复注释的编写量
• 信号注释不需要罗列所有连接的槽函数，只需要描述信号的触发场景、参数语义即可，具体连接逻辑属于业务代码的实现细节
• 如果信号对入参有特殊校验规则，可以在@pre标签中补充说明，比如入参不能为负数、浮点值不能为无穷大等

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