How to generate doxygen documentation for xml files comments?

Question

My current project is a C++ application. The documentation is generated with doxygen, and comments are formatted accordingly.
The project also includes several xml resource files, with comments. I would like to include them in the documentation.

Here is an illustration of the kind of thing I would like to do :

Input (file used by my application, 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>

Output (documentation generated by 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]

How should I write the comments, and which doxygen settings do I need ?

Answer 1

I HAVE A SOLUTION

I found a need to document my XML config files and since I use Doxygen for all of my other code I want to use Doxygen. The problem is that Doxygen doesn't support XML as a source code language (e.g. C++, Python, etc.) In fact the problem is worse than that, Doxygen tries to interpret the XML so hiding Doxygen tags in XML comments does no good (Doxygen will ignore anything in an XML comment).

Goal: document XML config file (config.xml) with doxygen tags. The tags MUST live in the XML file.

Solution:

1. Document the XML file (config.xml)
2. Generate a Doxygen aware document from the XML file (config.xml.md)
3. Configure Doxygen to process the Doxygen aware document (config.xml.md)

Here is a Makefile rule for what I'm talking about:

# 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

So the XML will look like this:

<!--
/// @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>

Tell Doxygen to read config.xml.md by adding the following to your Doxyfile. Be sure to add this after the initial FILE_PATTERNS assignment in your Doxyfile.

FILE_PATTERNS += *.xml.md

The given XML example will generate a page called "RM6x32 Configuration file" in the "Related Pages" section of your Doxygen documentation.

I hope that this helps and I hope that this spurs someone to create a more integrated solution.

Answer 2

AFAIK doxygen does not have support for documenting XML files.

The easiest thing I can think to do is to write an additional documentation file, as discussed in the question/answers How to include custom files in Doxygen and How to make an introduction page with Doxygen. In this file you can document the expected form of your input XML file as a separate page (using the \page command). This page will then appear under the Related Pages tab of your generated documentation. The file will look something like (note the use of C/C++ style comments):

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

*/

Unfortunately this method separates your documentation from your XML file.

Alternatively, other tools may do what you want. See for example this question: Can XML be documented using Doxygen, Sandcastle, or other documentation generators?