如何爲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

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?

Answer 2

我有一個解決方案

我發現了一個需要記錄我的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> 

告訴Doxygen的閱讀config.xml中.md將以下內容添加到您的Doxyfile中。請務必在Doxyfile中的初始FILE_PATTERNS賦值之後添加它。

FILE_PATTERNS += *.xml.md 

給出的XML示例將你的Doxygen文檔的「相關頁面」部分中生成一個名爲「RM6x32配置文件」頁面。

我希望這可以幫助，我希望這刺激了某人創造一個更加集成的解決方案。