Doxygen：如何包含一个降价页面来记录一个组

Question

我有一个相当复杂的项目，我想用 doxygen 记录它。

我在记录代码方面没有问题，而且我还设法使用自定义 README.md 文件以及 Doxyfile 中的“USE_MDFILE_AS_MAINPAGE = README.md”指令创建了一个漂亮的首页。

我定义了几个组 (@defgroup)，它们在我的文档中显示为“模块”。

除了常用的函数/变量/类型文档之外，我想为每个组添加一个“主页”以提供一般信息。

我尝试在组定义中添加自定义 MODULENAME.md 文件以及匹配的 @includedoc MODULENAME.md 条目，它似乎有效（我看到几行，如：“Generating docs for page md_mcu_noitr_coro_README...”），但我找不到页面是否以及在哪里已链接（我希望在模块的“详细说明”中看到它，因为如果我将一些文档内嵌在我放置“@includedoc”指令的位置，就会发生这种情况。

我的一个模块的 sn-p 是：

/**
 * @file coro.h
 * @brief definition of coroutine implementing functions.
 *
 * @date: Feb 8, 2018
 * @author: myself
 *
 * @defgroup coro "Coroutine implementation in plain 'C'."
 *
 * @includedoc mcu_noitr/coro/README.md
 * @{
 *
 */

我做错了什么？

注意： 这也有点令人惊讶，我需要将整个路径从我的 Doxyfile 所在的位置放置，否则即使它位于包含 @ 的文件旁边，doxygen 也不会找到它987654331@命令。

Answer 1

我还遇到了一个问题，即通过 \includedoc 或 \include{doc} 包含带有 Markdown 格式文本的文件不会导致正确解释的 Markdown。请注意，我包含了 other Markdown 文件中的 Markdown 文件。我的解决方法是在 Markdown 文件上使用广泛可用的 C 预处理器 (cpp)，并使用它的 #include 指令。您当然可以按照 cpp 手册页中的建议使用真正的通用文本处理器，例如 M4。将 Doxyfile 中的FILTER_PATTERNS 设置为：

FILTER_PATTERNS = *.md="cpp -P -traditional-cpp"

您需要-P 选项来避免它输出行标记，这会使 Doxygen 感到困惑。需要-traditional-cpp 以避免 cpp 吃掉对正确解释 Markdown 很重要的空白。不要使用单引号，因为这会导致 Doxygen 通过 sh 调用 cpp 时出错。

然后在我的 Markdown 主页中：

Main Page {#mainpage}
==========

Blah blah blah.

#include "other.md"

使用FILTER_PATTERNS 代替INPUT_FILTER 可以避免不允许添加或删除行的问题。

我的 markdown 文件在同一个目录中，我猜如果它们位于不同的位置，您可以通过 -I 告诉 cpp，这将满足您对您提交的 issue 上包含路径的期望.

Answer 2

目前 doxygen 不考虑像 \includedoc 这样的命令可以包含降价代码的事实。目前唯一的可能是编写一个过滤器，请参阅 doxygen 配置文件中的配置参数INPUT_FILTER，（未测试！）用该文件的代码替换 \includedoc`。