在Doxygen中如何标注函数参数仅可使用指定define宏定义值

核心文档编写要求 #

• 参数说明必须明确枚举所有合法取值：直接罗列出所有支持的宏常量，不要使用模糊表述，同时明确禁止直接传入对应整数魔数，避免使用者自行匹配数值传入
• 补充风险提示：明确告知用户如果传入未定义的整数值，会触发未定义行为、调用失败甚至程序崩溃等异常后果
• 搭配正反用法示例：同时给出正确、错误的调用示例，直观展示使用规则
• 如果使用Doxygen等自动化注释工具，建议用@warning、@note标签单独标注规则，优先级高于普通参数说明，更容易被使用者注意到

优化后的参考代码示例 #

#define API_TYPE1 0
#define API_TYPE2 1

/**
 * @brief 测试功能API
 * @param[in] argument1 接口类型参数，仅支持传入宏 `API_TYPE1` 或 `API_TYPE2`
 * @param[in] argument2 业务请求对应的URL字符串
 * @warning 禁止传入上述两个宏之外的任意整数值，否则会触发未定义行为
 * @return 调用状态码，0表示调用成功，非0表示调用失败
 */
int TestAPI(
    int argument1,
    string argument2
);

// ✅ 正确用法示例
TestAPI(API_TYPE1, "http://someurl.com");

// ❌ 错误用法示例，禁止使用
// TestAPI(0, "http://someurl.com"); // 直接传入魔数
// TestAPI(2, "http://someurl.com"); // 传入未在宏定义中声明的数值

可选的代码加固方案 #

仅靠文档约束可能存在遗漏，建议配合代码层面的校验进一步降低误用概率：

• 运行期校验：在函数入口处判断入参是否在合法范围内，不符合要求直接返回错误码或者触发调试断言
• 编译期校验：C语言可使用_Static_assert做静态校验，C++可配合类型约束、概念语法做编译期拦截，提前发现错误调用

内容的提问来源于stack exchange，提问作者Mohammad Hossein Amri