如何在Doxygen中包含自定义文件

Question

如何在Doxygen中包含自定义文件

doxygen

55

我想添加自定义（非项目）文件来生成一些额外的页面，使用Doxygen。

我不确定这些文件应该如何命名以及它们的内容应该如何格式化。

- Veger

5个回答

46

只是为了完整性：doxygen将3个可能的扩展名视为附加文档文件：.dox，.txt和.md。

扩展名为.dox和.txt的文件在文件索引中是隐藏的，并且被视为普通源文件，只是没有那么多源代码。

在这些文件中，您至少需要一个C/C++风格的注释块，您可以在其中填写文档。

扩展名为.md的文件被视为使用Markdown格式进行文档编写。这些被视为相关页面。

- doxygen

22

似乎现在，.md需要被添加到这个列表中，这仍然是谷歌上非常流行的。 - Lukx

使用doxygen 1.8.13版本，.txt文件无法工作。.md文件对我来说可以工作。 - Fabian

@Fabian，请查看Doxygen配置文件（Doxyfile）中的EXTENSION_MAPPING标签。 - albert

1

@albert 谢谢。这允许添加txt文件，但是我需要选择一种语言来解析它们，并在txt文件中使用doxygen注释。Markdown文件会自动被视为doxygen页面，而无需修改md文件，这也是我对txt文件的期望。 - Fabian

@Fabian，我想我理解了你的问题，在文档中没有提到Markdown的可能性。你可能需要：EXTENSION_MAPPING = txt=md。 - albert

17

为了更加完整，从Doxygen版本1.8开始（据我所知），它现在支持与markdown语法非常相似的其他文本文件。您不再需要使用C / C ++样式的注释块。相反，只需编写几乎正常的文本，并确保文本文件位于输入路径中，并且您的Doxygen扫描实际上查找具有.markdown扩展名（或您选择使用的任何其他扩展名，例如.md）的文件。

- DXM

我不确定（或许可以把这个当做一个问题），但是我没有看到在Markdown文档中添加像\dot这样的命令的方法。 - pedz

@pedz：我已经有一段时间没有玩Doxygen了（一段时间前换了工作），所以不记得所有细节。您无法将任何自定义标签添加到Markdown中。它必须由解析器支持，但我相信“\dot”是一个有效的标签：http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmddot。因此可能a）您没有正确的版本或b）在配置文件中您没有指定DOT工具可用。 - DXM

11

为了清晰明了起见：

在 .dox 配置文件中，使用如下方式将该文件添加到 INPUT 指令中：

INPUT = ../src \
        ../include \
        ../docs/my-extra-file.txt

如果文件具有适当的扩展名，比如.h或.c，那么Doxygen将在不添加到INPUT指令的情况下找到该文件。在文件内部使用普通的Doxygen标签，就像在源代码中一样，即在注释块内部，例如：

/*! \mainpage MyProject - A Brief Description.
\image html Mylogo.png
\section my-intro MyProject Introduction
\htmlinclude about-MyProject.html
*/

在代码中任何地方都可以使用包含标签之一，例如上面示例中的“\htmlinclude”。

- Wiley

1

只需在您的doxyfile中的INPUT宏中列出您的自定义文件即可。您可以选择任何您认为合适的名称。格式是带有Doxygen标记的文本。

- mouviciel

我尝试过那样做，但文件被包含为源文件（添加到文件列表中）。使用dox扩展名似乎可以防止这种情况。 - Veger

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Veger · Accepted Answer

我在找到答案之前进行了相当多的搜索，所以我想分享一下！

根据这篇Doxygen gotchas文章，我最终发现：您需要添加一个扩展名为dox的文件。它的内容应该包含C风格的注释块：

/*!
  \page My test page
  contents
  ...
  more contents
*/

确保您的自定义文件放置在已包含在INPUT设置中的目录中，或者如果未设置INPUT，则放置在当前目录中，以便这些文件可以被找到。