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 */

然后正确获取这些宏的文档。

如果您不想更改来源，则可以在EXCLUSIVE_MACRO_ONE中添加PREDEFINED和朋友，而无需设置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

注意，无需更改默认的Doxygen设置

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

在Doxygen中记录条件专用代码

2 个答案: