如何让Doxygen识别自定义返回值、参数提示宏并正确解析函数声明？

出现该问题的核心原因是Doxygen的C/C++语法解析器默认不会主动处理你自定义的空语义宏，会将这些宏视作独立的语法单元拆分解析，因此才会出现返回类型、函数名识别错误的问题。你可以通过以下两种方案解决：

方案1：修改Doxyfile全局配置（推荐） #

直接在Doxygen的配置文件中添加自定义宏的展开规则，不需要修改业务代码：

1. 找到Doxyfile中的以下配置项，修改为对应值：

# 开启Doxygen的预处理器宏展开功能
MACRO_EXPANSION = YES
# 仅展开显式指定的预定义宏，避免影响项目中其他正常宏的解析
EXPAND_ONLY_PREDEF = YES
# 预定义你的自定义提示宏，替换为Doxygen可识别的标准语法
PREDEFINED = notnull= \
             issizeof(__T)= \
             "GenericPtr(__T)=void*"

2. 重新生成文档即可。此时Doxygen在预处理阶段会自动抹除notnull、issizeof(T)标记，将GenericPtr(T)替换为标准的void*类型，即可正确识别函数声明的返回值、函数名和参数列表。

如果你希望在生成的文档中保留这些宏的语义提示，可以调整PREDEFINED的定义，将宏替换为带注释的结构：

PREDEFINED = "notnull=/** @note 返回值非空 */" \
             "issizeof(__T)=/** @note 入参应为 __T 类型的大小 */" \
             "GenericPtr(__T)=/** 指向 __T 类型的 */ void*"

这样生成的文档会自动携带对应提示，保留你设计这些宏的原有语义。

方案2：在代码中添加Doxygen专用的宏定义 #

如果你不想修改全局Doxyfile配置，可以在宏定义的头文件中添加Doxygen专用的条件分支：

#ifdef DOXYGEN
/**
 * @def notnull
 * @brief 标记指针类型返回值/参数非空
 */
#define notnull
/**
 * @def issizeof(__T)
 * @brief 标记size_t类型参数应传入__T类型的大小
 * @param __T 目标内存对应的类型
 */
#define issizeof(__T)
/**
 * @def GenericPtr(__T)
 * @brief 返回指向__T类型的通用指针
 * @param __T 目标内存对应的类型
 * @return void* 指向__T类型的指针
 */
#define GenericPtr(__T) void*
#endif

之后在Doxyfile的PREDEFINED配置项中添加DOXYGEN=1即可，Doxygen处理代码时会优先使用该分支下的宏定义完成解析，同时还能自动生成这些提示宏的说明文档。

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