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文件中。

解决方案：

记录XML文件（config.xml）
从XML文件（config.xml.md）
配置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 ++样式注释）：

/* \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?

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

2 个答案: