如何为 xml 文件注释生成 doxygen 文档？

Question

我当前的项目是一个 C++ 应用程序。文档是使用 doxygen 生成的，并且 cmet 会进行相应的格式化。
该项目还包括几个带有 cmets 的 xml 资源文件。我想将它们包含在文档中。

这是我想做的那种事情的插图：

输入（我的应用程序使用的文件，myFile.xml）：

<!-- 
@brief settings used by class MyClass at startup
@image html screenshot_default.jpg
-->
<Myclass_settings id="default_setting">
  <param_1 value="1"/>
  <param_2 value="XXXXX"/>
</Myclass_settings>

<!-- 
@brief settings used by class MyClass - reserved to experienced users
@image html screenshot_advanced.jpg
-->
<Myclass_settings id="advanced_setting">
  <param_1 value="42"/>
  <param_2 value="WWWWW"/>
</Myclass_settings>

输出（doxygen 生成的文档）：

myFile.xml File Reference
    Elements
        default_setting    
            settings used by class MyClass at startup
            [here screenshot_default is inserted]
        advanced_setting   
            settings used by class MyClass - reserved to experienced users      
            [here screenshot_advanced is inserted]

我应该如何编写 cmets，我需要哪些 doxygen 设置？

Answer 1

我有一个解决方案

我发现需要记录我的 XML 配置文件，并且由于我将 Doxygen 用于所有其他代码，因此我想使用 Doxygen。问题是 Doxygen 不支持将 XML 作为源代码语言（例如 C++、Python 等）。事实上，问题比这更糟糕，Doxygen 试图解释 XML，因此在 XML cmets 中隐藏 Doxygen 标记没有好处（ Doxygen 将忽略 XML 注释中的任何内容。

目标：使用 doxygen 标签记录 XML 配置文件 (config.xml)。标签必须存在于 XML 文件中。

解决方案：

1. 记录 XML 文件 (config.xml)
2. 从 XML 文件 (config.xml.md) 生成 Doxygen 感知文档
3. 配置 Doxygen 以处理 Doxygen 感知文档 (config.xml.md)

这是我所说的 Makefile 规则：

# Generate a doxygen aware file from the XML
#
config.xml.md: config.xml
    # Take all lines starting with '///'.
    # Then use sed to remove the '///' string.  The result will be a 
    # markdown document
    #
    grep "^///" $^ | sed 's/^\/\/\///' > config.xml.md

所以 XML 将如下所示：

<!--
/// @page RM6x32 RM6x32 Configuration file.
/// 
/// The product tag defines the product that we are targeting.  Currently there
/// is only one product supported: RM6x32.
/// 
-->
<product name='RM6x32'>
    <tuner>
    </tuner>
</product>

通过将以下内容添加到您的 Doxyfile 来告诉 Doxygen 读取 config.xml.md。请务必在 Doxyfile 中的初始 FILE_PATTERNS 分配之后添加它。

FILE_PATTERNS += *.xml.md

给定的 XML 示例将在 Doxygen 文档的“相关页面”部分生成一个名为“RM6x32 配置文件”的页面。

我希望这会有所帮助，我希望这能激励人们创建一个更集成的解决方案。

Answer 2

AFAIK doxygen 不支持记录 XML 文件。

我能想到的最简单的事情是编写一个额外的文档文件，如问题/答案中所述 How to include custom files in Doxygen 和 How to make an introduction page with Doxygen。在此文件中，您可以将输入 XML 文件的预期形式记录为单独的页面（使用 \page 命令）。然后，此页面将出现在您生成的文档的 Related Pages 选项卡下。该文件将类似于（注意使用 C/C++ 样式 cmets）：

/* \page input_xml_page myFile.xml File Reference

\section elements Elements

Some preliminary discussion of the file goes here...

You can refer to both the default \ref default_settings and advanced settings
\ref default_settings sections like this.

\subsection default_settings Default settings

Settings used by class MyClass at startup
\image html screenshot_default.jpg

\subsection advanced_settings Advanced settings

Settings used by class MyClass - reserved to experienced users
\image html screenshot_advanced.jpg

*/

不幸的是，这种方法将您的文档与 XML 文件分开。

或者，其他工具可能会做你想做的事。例如看这个问题： Can XML be documented using Doxygen, Sandcastle, or other documentation generators?