如何使用 Doxygen 定义文档构建选项和定义

Question

问题上下文：

doxygen 1.8.14 / Eclipse CDT 2021-03 / Eclox 0.12.1 / macOS 10.15.7

该项目是纯 C 语言，并为此进行了配置。

这个问题与仅从裸代码自动生成的文档有关，而不是我自己的任何注释标记。

---

在 Doxygen 中，使用 Enable Preprocessing YES，它会分析条件构建标志，并且不会记录这些标志内的代码。

如果Enable Preprocessing 否，Doxygen 会记录这些标志内的代码，但不会记录所有基本的#define 语句。

我不理解这个非此即彼的观点。我两个都想要。

我已经摆弄了所有预处理选项（例如Macro Expansion）并且无法获得我需要的东西。看起来我可以手动列出我想要包含的定义，但对于 100k LOC 项目，这是不现实的。

为每个构建变体构建多个文档版本，其中 97% 是相同的（虽然我认为对某些人有用）对于我的目的来说是一个蹩脚的解决方案——文档的重点是让软件工程师理解选项上下文中的整个系统，而不仅仅是它的一种视图。

我是否在某处缺少解决此问题的配置选项？感谢阅读。

// Examples (out of context):
//
// Build option system:

#define mBUILD_PLATFORM_105  (1U)
#define mBUILD_PLATFORM_205  (2U)
#define mBUILD_PLATFORM_300  (3U)
#define mBUILD_PLATFORM_320  (4U)
#define mBUILD_FOR_PLATFORM  (mBUILD_PLATFORM_105)

// Then in code somewhere...

#if (mBUILD_FOR_PLATFORM == mBUILD_PLATFORM_105)
// This could be a few lines, could be a whole function,
// or even a whole library suitable only for 105.
#endif

// Meanwhile, there are many of these...

#define mYADDA_SENSOR_COUNT_MAX  (12U)

Eclox UI 预处理器选项：

---

更新 2：

// Differences from a baseline doxyfile (not including the obvious
// project-specific name, source path, etc.)

REPEAT_BRIEF           = NO
ABBREVIATE_BRIEF       =
OPTIMIZE_OUTPUT_FOR_C  = YES
EXTRACT_ALL            = YES
EXTRACT_PRIVATE        = YES
RECURSIVE              = YES
HTML_EXTRA_STYLESHEET  = assets/mDoxStyles.css *
ENUM_VALUES_PER_LINE   = 1
SEARCHENGINE           = NO
GENERATE_LATEX         = NO
CLASS_DIAGRAMS         = NO
DIRECTORY_GRAPH        = NO

// * I've made minor changes to text size, color and spacing.
//   Nothing structural.

---

更新 3：

我使用 4 个文件来尝试解释。我已经绘制了这些文件的图表，希望可以全面查看，以便您参考。

从左侧开始 mProject.h —— 这是我之前展示的构建定义，并且为了更好地衡量另一个定义以及文件的“Dox-umentation”和一个定义。

接下来是 mMutex.h，它是程序员将在整个应用程序中使用的外观 API。这还包含文件的 Dox-umentation 和定义。

接下来的两个文件 mMutex_rtos 和 mMutex_macos 是 mMutex 外观的实现细节。请注意构建条件包装几乎整个文件。

好的，那么，Doxygen 1.8.14 对这些文件做了什么...

我在一个简单的文本编辑器中编写了这些文件，并使用 Doxygen GUI（没有 Eclipse 或 Eclox）运行这些文件。我正在使用的唯一 Doxygen 设置是 ENABLE_PREPROCESSING 和 EXTRA_ALL。请注意，构建条件设置为 mOS_MACOS。

使用 ENABLE_PREPROCESSING = YES 和 EXTRACT_ALL = YES

• Project.h -- 所有定义都记录在案（信息呈现在 html 文件中）。
• mMutex.h -- 处理完整文件并记录在 html 文件中呈现的 @file 和 @var 信息。
• mMutex_macos.h -- 该文件有完整的文档，所有细节都以 html 呈现。
• mMutex_rtos.h -- 文件显示在文件列表中，html 页面仅显示#include，没有呈现其他文档。如果我设置 EXTRACT_ALL = NO，则文件名会显示在文件列表中，但没有指向后续 html 页面的链接。

我在这种情况下遇到的问题是文档中没有捕获 mMutex_rtos 文件的任何内容。在这种风格中，构建条件是包装整个文件或整个函数，而不仅仅是函数中的几行内联，那么文档最终会丢失。

ENABLE_PREPROCESSING = NO 和 EXTRACT_ALL = YES

• Project.h -- @file 信息被渲染，但没有任何定义包含在 html 文件中。 Dox 的常用渲染和我明确的 @var 内容都不存在。
• mMutex.h -- 函数使用 Dox 的默认内容呈现，但 html 文件中缺少 mMUTEX_NAME_LENGTH_MAX。 Dox 的常用渲染和我明确的 @var 内容都不存在。
• mMutex_macos.h -- 该文件有完整的文档，所有细节都以 html 呈现。但是，如果有 #define 它，它就会丢失。
• mMutex_rtos.h -- 现在该文件已完整记录，所有详细信息均以 html 呈现。但是，如果有 #define 它，它就会丢失。

打开/关闭 EXTRACT_ALL 时我注意到的是，即使没有我自己的 @fn 文本，它也会为定义和函数添加大的选项卡式部分。否则，当 ENABLE_PREPROCESSING = Y 时，我认为 EXTRACT_ALL 不会改变 html 文件中包含的内容。

因此，我似乎可以选择消除所有#defines（不是选项），或者排除在编译文档时任何构建选项未激活的所有文档。

（我很快就会尝试 1.9.x。）

---

• 已更新，包括上下文注释、一些文本编辑、Eclox UI 图像。
• 更新 2 以包含 doxyfile 差异。
• 更新 3 以提供更详细的文件示例。

Answer 1

不是答案，而是测试给定信息的结果。

我将提供的代码转储到 aa.h 文件中，并将提供的设置（CSS 设置除外）转储到 Doxyfile 中，并使用 1.8.14 和 1.9.1 版本运行

在这两种情况下，我得到了相同的输出：

根据给定的信息，这看起来对我来说还可以。 你错过了什么还是我忽略了什么？