xml - 如何为 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 文件 (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 配置文件”的页面。

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