如何为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 文件分开。

或者，其他工具也可以完成您想要的操作。例如，参见这个问题： Can XML be documented using Doxygen, Sandcastle, or other Documentation Generators?