在 Doxygen 中记录条件独占代码

Question

考虑

// EXTERNAL_MACRO is an external macro defined to some value by build system

#if EXTERNAL_MACRO == 1
#   define EXCLUSIVE_MACRO_ONE
#elif EXTERNAL_MACRO == 2
#   define EXCLUSIVE_MACRO_TWO
#else
#   define EXCLUSIVE_MACRO_OTHER
#endif

在构建时，只定义了一个 EXCLUSIVE_MACRO_... 宏。

如何在 Doxygen 中记录所有三个 EXCLUSIVE_MACRO_... 宏？

PREDEFINED 配置设置对此没有帮助，因为它允许将 EXTERNAL_MACRO 定义为仅单个值（因此仅记录单个 EXCLUSIVE_MACRO_...）。

此 SO answer 提供了一种解决方案，可以完成这项工作，但它需要额外的逻辑。我正在寻找一个更简单的答案，一个使用 Doxygen 配置（如果可能的话）而不是修改原始代码的答案（尽管一些修改当然可以）。

Answer 1

查看相关问答： Document a config macro with doxygen

基本上：

在doxygen配置文件中，添加：

PREDEFINED = IN_DOXYGEN

在源代码的某处，添加：

/*
  Exporting build configuration macros to doxygen,
  so they get documented.
*/
#ifdef IN_DOXYGEN
#   define EXCLUSIVE_MACRO_ONE
#   define EXCLUSIVE_MACRO_TWO
#   define EXCLUSIVE_MACRO_THREE
#endif /* IN_DOXYGEN */

然后这些宏的文档就被正确地挑选出来了。

如果不想改源，可以在PREDEFINED添加EXCLUSIVE_MACRO_ONE和好友，而不是设置EXTERNAL_MACRO。

Answer 2

灵感来自answer。

问题：我们有一个现有的头文件，它基于一个外部宏（由构建系统提供），在编译期间定义了几个专有宏之一。由于只定义了一个编译时宏（针对每个单独的构建），因此很难将 Doxygen 文档添加到所有专有选项中。

// DEFINED_EXTERNALLY is a macro provided by the build system (e.g. via -D). It is defined as 1, 2, or some other natural number.

// Based on DEFINED_EXTERNALLY we want to define one of several exclusive DEFINED_HERE_... macros (e.g. DEFINED_HERE_1, DEFINED_HERE_2, and DEFINED_HERE_OTHER).

// First, we check that none of the DEFINED_HERE_... macros is defined yet.
#if defined(DEFINED_HERE_1) || defined(DEFINED_HERE_2) || defined(DEFINED_HERE_OTHER)
#   error "Conflict: macro DEFINED_HERE_... is already defined!"
#endif

// Then, we define one, and only one, of the DEFINED_HERE_... macros.
#if DEFINED_EXTERNALLY == 1
#   define DEFINED_HERE_1
#elif DEFINED_EXTERNALLY == 2
#   define DEFINED_HERE_2
#else
#   define DEFINED_HERE_OTHER
#endif

解决方案：我们临时定义了 DEFINED_HERE_... 宏的所有变体及其文档。这将导致 Doxygen 为所有这些生成文档。然后我们取消定义所有变体并恢复正常的宏定义逻辑。 因此，我们将拥有所有变体的文档，但在编译期间只会定义其中一个，就像添加文档之前的情况一样。

原始代码

// DEFINED_EXTERNALLY is a macro provided by the build system (e.g. via -D). It is defined as 1, 2, or some other natural number.

// Based on DEFINED_EXTERNALLY we want to define one of several DEFINED_HERE_... macros (e.g. DEFINED_HERE_1, DEFINED_HERE_2, and DEFINED_HERE_OTHER).

// First, we check that none of the DEFINED_HERE_... macros is defined yet.
#if defined(DEFINED_HERE_1) || defined(DEFINED_HERE_2) || defined(DEFINED_HERE_OTHER)
#   error "Conflict: macro DEFINED_HERE_... is already defined!"
#endif

用于生成文档的新插入代码

/// \brief Value 1.
/// \details It does the following...
#define DEFINED_HERE_1
#undef DEFINED_HERE_1
/// \brief Value 2.
/// \details It does the following...
#define DEFINED_HERE_2
#undef DEFINED_HERE_2
/// \brief Other value.
/// \details It does the following...
#define DEFINED_HERE_OTHER
#undef DEFINED_HERE_OTHER

原始代码

// Then, we define one, and only one, of the DEFINED_HERE_... macros.
#if DEFINED_EXTERNALLY == 1
#   define DEFINED_HERE_1
#elif DEFINED_EXTERNALLY == 2
#   define DEFINED_HERE_2
#else
#   define DEFINED_HERE_OTHER
#endif

NB 不需要更改默认的 Doxygen 设置

ENABLE_PREPROCESSING   = YES
MACRO_EXPANSION        = NO
EXPAND_ONLY_PREDEF     = NO
PREDEFINED             =
EXPAND_AS_DEFINED      =