背景
我正在使用doxygen为C语言编写的项目进行文档化。在该项目中有很多重复的代码。 由于我仅限于使用纯C(不允许使用C ++),因此我使用宏来减少源文件中的重复内容。 在宏生成的代码中,我希望包括函数和类型声明(它们遵循一定的模式,实际的宏编写起来相当容易)。 我真的希望这些生成的函数和类型出现在doxygen文档中,因为它们对于库API非常重要。但是,我很难使doxygen正确展开宏。
问题
Doxygen并不总是展开宏。例如,在同一行代码中,第一次调用函数样式宏时会展开,但第二次则不会。
我认为解释这个问题最好的方法是通过展示一个MRE(可以从这里下载)
示例源文件
考虑以下文件singlefile.h
/** @file singlefile.h
@defgroup singlefile singlefile.h: Single File Example
Test file
@{
*/
#ifndef _SINGLE_FILE_H
#define _SINGLE_FILE_H
#define _CCONCAT(X, Y) X ## Y
#define _CONCAT(X, Y) _CCONCAT(X, Y)
#define CONCAT(X, Y) _CONCAT(X, Y)
#define MY_TYPE_FULL(MY_TYPE) CONCAT(My, MY_TYPE)
#define MY_TYPEDEF_H(MY_TYPE) typedef struct MY_TYPE_FULL(MY_TYPE) MY_TYPE_FULL(MY_TYPE);
MY_TYPEDEF_H(Account)
#endif
/** @} */
宏调用 MY_TYPEDEF_H(Account)
的预期输出是以下类型声明
typedef struct MyAccount MyAccount;
在C预处理器中,这个功能可以正常工作(也通过https://godbolt.org/进行了验证),但在doxygen中却不行。doxygen预处理器的输出为:
Preprocessing /home/<username>/Documents/doxygenmacroexpand/src/singlefile.h...
Preprocessor output (size: 296 bytes):
---------
00001 /** @file singlefile.h
00002 @defgroup singlefile singlefile.h: Single File Example
00003 Test file
00004 @{
00005 */
00006
00007
00008
00009
00010 #define _CCONCAT(X, Y)
00011 #define _CONCAT(X, Y)
00012 #define CONCAT(X, Y)
00013
00014 #define MY_TYPE_FULL(MY_TYPE)
00015 #define MY_TYPEDEF_H(MY_TYPE)
00016
00017 typedef struct MyAccount MY_TYPE_FULL( Account );
00018
00019
00020
00021 /** @} */
00022
---------
Macros accessible in this file:
---------
_CCONCAT _CONCAT MY_TYPE_FULL MY_TYPEDEF_H CONCAT
---------
因此,HTML 文档具有以下类型声明:
struct MyAccount MY_TYPE_FULL (Account)
这导致我的实际项目的文档十分混乱,因为我有更多层次的宏调用。
我发现很奇怪的是,同一个宏第一次被扩展了,但第二次没有。
Doxyfile
我使用了doxygen1.8.17
生成的全新Doxyfile。我将以下标签与默认值不同地设置了:INPUT = ./src
OUTPUT_DIRECTORY = ./doc
MACRO_EXPANSION = YES
OPTIMIZE_OUTPUT_FOR_C = YES
这是目录结构(使用
tree
命令输出的):.
├── Doxyfile
└── src
└── singlefile.h
问题
如何使doxygen正确地展开所有宏?
简而言之,C源文件中的一些宏被doxygen预处理器展开,而另一些则没有展开,即使在相同的调用深度下也是如此。这会导致在最简单的情况下部分生成的文档以及在我真实项目的场景下完全无用的文档。
附注:这是我在SO上发布的第一个问题。通常我能找到可以解决我的问题的答案,但这一次不行。无论如何,如果您有任何有关我应该如何发布问题的建议,我非常愿意听取反馈意见。
00017 typedef struct MyAccount MyAccount;
。建议更新到版本1.9.1。(对于完整的问题和显示doxygen -d preprocessor
输出的事实,OP获得了一个大加分)。 - albert