在 doxygen 中记录#undef 的好方法答案

【问题标题】：Good way to document #undef in doxygen在 doxygen 中记录#undef 的好方法
【发布时间】：2011-04-03 07:19:25
【问题描述】：

我目前有几个#define in c 文件，它们关闭了硬件的某些功能以进行测试。但是，当它们未定义时，我想用 doxygen 记录它们。

例如：

这很好用：

/// \def SIMULATE_SOME_HW_INTERFACE
/// Define this when you want to simulate HW interface.
#define SIMULATE_SOME_HW_INTERFACE

当您将 #define 更改为 #undef 时，您会在 doxygen 中收到警告，并且它不会显示在 doxygen 生成的输出中。我想记录这个 #define 是否已定义或未定义。

如何强制 doxygen 记录 #undef???

【问题讨论】：

可能最好的解决方案不是#define 你需要的#undef-ine。根据我的经验，#undef 仅用于进行技巧/黑客攻击
这是一种黑客行为。我想编写大量代码来处理未安装在开发机器上的专用硬件，但在需要在实际目标机器上运行时轻松启用它。
作为关于 undef 的一个非常重要的警告 - 我曾经为 Apple 修复了一个已经存在 18 个月的错误。 Quicktime 标头依赖于递归地包含在条件定义中，并且传统的保护变量未定义。后来，有人添加了#pragma once，这意味着编译器破坏了递归包含。

标签： doxygen undef

【解决方案1】：

在仅由 Doxygen 包含的头文件中定义它们（放置在与主源代码不同的目录树中）。

通过使用仅在 Doxygen 设置中定义的定义包装此头文件来保护此头文件，例如：

#ifdef ONLY_FOR_DOXYGEN

/// \def SIMULATE_SOME_HW_INTERFACE
/// Define this when you want to simulate HW interface.
#define SIMULATE_SOME_HW_INTERFACE

#endif

我还使用它来有条件地将 lightweight class definitions 包含在 MFC 基类之类的东西中，这样它们就可以作为类层次结构的基础出现，而无需解析所有 MFC。

【讨论】：

【解决方案2】：

我通过在#define 下添加#undef 找到了一种笨拙的方法。这样它是为 Doxygen 定义的，但立即为编译器未定义。

/// \def SIMULATE_SOME_HW_INTERFACE
/// Define this when you want to simulate HW interface.
/// Comment out #undef to simulate HW interface
#define SIMULATE_SOME_HW_INTERFACE
#undef  SIMULATE_SOME_HW_INTERFACE

我试图弄清楚如何使用 PREDEFINED 选项在 Doxyconfig 文件中设置 SIMULATE_HW_INTERFACE。无法让它工作。所以这是我迄今为止最好的解决方案。

【讨论】：

顺便说一句，它看起来很奇怪（一些静态分析器可能会注意到）
我同意你的看法。这只是一种解决方法。我希望有人知道如何强制 doxygen 记录#undef。

【解决方案3】：

我通过在主头文件中记录这样的编译器标志解决了我的问题：

/**
 * \defgroup flags Compilerflags
 */

/**
 * \def MY_FLAG
 * \ingroup flags
 * Dokumentation....
 */
#ifndef MY_FLAG
#define MY_FLAG
#undef MY_FLAG
#else
#define MY_FLAG
#endif

这样一切正常：doxygen 和编译，你可以继续在命令行中指定你的标志...

【讨论】：