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

Question

我当前的项目是一个C ++应用程序。 使用doxygen生成文档，并相应地格式化注释。
该项目还包括几个带注释的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]

我该如何撰写评论，以及我需要哪些doxygen设置？

Answer 1

我有一个解决方案

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

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

解：

1. 记录XML文件（config.xml）
2. 从XML文件生成Doxygen感知文档（config.xml.md）
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文件。

我能想到的最简单的事情是编写一个额外的文档文件，如问题/答案中所讨论的如何在Doxygen中包含自定义文件以及如何使用Doxygen创建介绍页面 。 在此文件中，您可以将输入XML文件的预期形式记录为单独的页面（使用\\page命令）。 然后，此页面将显示在生成的文档的“ Related Pages选项卡下。 该文件看起来像（注意使用C / C ++样式注释）：

/* \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文件分开。

或者，其他工具可以做你想要的。 例如，请参阅此问题： 可以使用Doxygen，Sandcastle或其他文档生成器记录XML吗？