Doxygen：如何包括一个标记页来记录一个组

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

我在编写代码文档方面没有问题，而且我还使用了自定义的

README.md

文件以及Doxyfile中的“

USE\u MDFILE\u AS\u MAINPAGE=README.md

”指令，获得了一个不错的首页

我定义了几个组（

@defgroup

），它们在我的文档中显示为“模块”

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

我尝试在组定义中添加自定义的

MODULENAME.md

文件以及匹配的

@includedoc MODULENAME.md

条目，这似乎有效（我看到了几行代码，如：“

为页面md\u mcu\u noitr\u coro\u README生成文档…

”），但我找不到页面是否链接以及链接到哪里（我希望在模块的“详细描述”，如果我将一些文档内联到“

@includedoc

”指令的位置，就会发生这种情况

我的其中一个模块的一个片段是：

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

我做错了什么

---

注释：还有一点奇怪，我需要把整个路径从我的<代码> doxfile 中去掉，否则doxGEN就不会找到它，即使它正好在包含<代码> @包含Debug DOC < /C>命令的文件旁边。t目前唯一的可能是编写过滤器，请参阅doxygen配置文件中的配置参数

INPUT\u filter

（未测试！）将\includedoc`替换为该文件的代码。

我还遇到了一个问题，即通过

\includedoc

或

\include{doc}包含带有标记格式文本的文件

无法正确解释标记。请注意，我包含了其他标记文件中的标记文件。我的解决方法是使用C预处理器（cpp）-广泛可用-在标记文件上，并使用它的

#include

指令。当然，您可以使用真正的通用文本处理器，如cpp手册页中建议的。在Doxyfile中设置

过滤器模式

：

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

您需要使用

-p

选项来避免输出线标记，这会混淆Doxygen。需要使用

-传统cpp

来避免cpp占用空白，这对于正确解释标记非常重要。当Doxygen通过

sh

调用

cpp

时，不要使用单引号，因为这会导致错误> 然后在我的降价主页中：

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

Blah blah blah.

#include "other.md"

使用

FILTER\u PATTERNS

而不是

INPUT\u FILTER

可以避免不允许添加或删除行的问题

---

我把我的标记文件放在同一个目录中，我想如果它们位于不同的地方，你可以通过

-I

告诉cpp，这将满足你对在你的文件中包含路径的期望。

首先是关于注释。你需要Doxyfile所在位置的相对路径，或者更好地说是从d的位置氧气启动并不奇怪，因为可能有多个

README.md

文件，此时doxygen应该会猜测。为什么要通过一个单独的文件来执行此操作。你不能直接在defgroup命令中包含标记代码吗？@albert:我想添加一个单独的文件，因为它是一个重要的pi它会将“真正的代码”向下推几百行；另一个原因是使用真正的标记编辑器会简化编写，而不是在多行“C”注释中。关于注释：我希望正常的“#包括“行为：计算相对于包含文件的路径；Doxygen将有所有数据可以猜测正确。关于位置和编辑的推理非常有效。关于‘注释’，请在Doxygen错误跟踪（）中提交一个问题。”.在前面的评论中忘记：您使用的是哪个版本的doxygen？只是做了一个小测试，看起来不起作用，据我所知，这是由于标记解析的时刻。可能包含的文档必须经过“标记预处理”。可能最好在doxygen错误跟踪中提交一个问题（github.com/doxygen/doxygen/issues/new）包括一个小的、自包含的示例（tar或zip中的source+config文件）来重现该问题？我将进行探索，但第一次阅读看起来不太好：请注意，筛选器不得添加或删除行；它是在扫描代码之前应用的，而不是在生成输出代码时应用的。如果添加或删除行，将无法正确放置定位点。“我同意，

INPUT\u FILTER

可能因为您提到的参数而无法工作，因此这个问题可能是唯一的解决办法（：-（）嗯……我看到了一个很长的积压补丁列表（包括您于2014年2月23日发布的一个！）。在您看来，doxygen core group的响应能力如何？取决于修补程序是否存在积压，但正如您所看到的，我最近添加了相当多的建议修补程序。目前，master中有78个修补程序不在最新版本中，并且还有一些直接来自Dimitri的修补程序。建议的修补程序并不总是能够将其添加到发行版中，因为它违背了doxygen的理念或破坏了其他一些代码。doxygen核心团队没有那么大（Dimitri），除了正常工作之外，还有其他任务需要完成（这都是自愿的！）。今年的其他一些任务是从bugzilla转移到github问题跟踪器，将文件宿主/电子邮件地址从stack.nl转移到sourceforge/gmail，…我无法实现这一点。当我按照建议使用

FILTER\u PATTERNS=*.md=“cpp-P-traditional cpp”

时，.md文件不会显示任何内容。