Doxygen 不一致地扩展 C 宏
Doxygen inconsistently expands C macros
上下文
我在用 C 编写的项目中使用 doxygen 作为文档。
在那个项目中有很多重复的代码。
由于我仅限于使用纯 C(不允许使用 C++),因此我使用宏来减少
源文件中的重复。
在由宏生成的代码中,我希望包含函数和类型声明(它们遵循一种模式,实际的宏相当容易编写)。
我真的希望这些生成的函数和类型出现在 doxygen 文档中,因为它们对库 API 至关重要。但是,我正在努力让 doxygen 正确扩展宏
问题
Doxygen 并不总是扩展宏。例如。在同一行代码中,同一个类似函数的宏被调用两次,第一次展开但第二次没有展开。
我觉得最好的解释这个问题的方法是展示一个MRE(你可以从here下载)
示例源文件
考虑以下文件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)
这导致我的实际项目产生了纯粹的垃圾文档,其中我有更多层的宏调用。
我觉得很奇怪的是,同一个宏第一次展开但第二次没有展开。
Doxy文件
我使用了一个由 doxygen 1.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 上的第一个 posted 问题。通常我找到的答案可以让我解决我的问题,但不是他的时间。无论如何,如果您对我应该如何 post 提问
有任何建议,我愿意接受反馈
版本 1.8.17 于 2019 年 12 月 27 日发布,存在所示问题。
使用 doxygen 版本 1.8.18(2020 年 4 月 4 日),问题消失了,当前版本 1.9.1 也是如此。
在所有这些情况下,我确实看到了
00017 typedef struct MyAccount MyAccount ;
建议更新到1.9.1版本。
上下文
我在用 C 编写的项目中使用 doxygen 作为文档。 在那个项目中有很多重复的代码。 由于我仅限于使用纯 C(不允许使用 C++),因此我使用宏来减少 源文件中的重复。 在由宏生成的代码中,我希望包含函数和类型声明(它们遵循一种模式,实际的宏相当容易编写)。 我真的希望这些生成的函数和类型出现在 doxygen 文档中,因为它们对库 API 至关重要。但是,我正在努力让 doxygen 正确扩展宏
问题
Doxygen 并不总是扩展宏。例如。在同一行代码中,同一个类似函数的宏被调用两次,第一次展开但第二次没有展开。
我觉得最好的解释这个问题的方法是展示一个MRE(你可以从here下载)
示例源文件
考虑以下文件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)
这导致我的实际项目产生了纯粹的垃圾文档,其中我有更多层的宏调用。
我觉得很奇怪的是,同一个宏第一次展开但第二次没有展开。
Doxy文件
我使用了一个由 doxygen 1.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 上的第一个 posted 问题。通常我找到的答案可以让我解决我的问题,但不是他的时间。无论如何,如果您对我应该如何 post 提问
有任何建议,我愿意接受反馈版本 1.8.17 于 2019 年 12 月 27 日发布,存在所示问题。 使用 doxygen 版本 1.8.18(2020 年 4 月 4 日),问题消失了,当前版本 1.9.1 也是如此。 在所有这些情况下,我确实看到了
00017 typedef struct MyAccount MyAccount ;
建议更新到1.9.1版本。