How to create doxygen documentation for comments on xml files?

Question

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

Here is an illustration of what 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> 

Exit (documentation created 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 do I write comments and what doxygen settings do I need?

Answer 1

AFAIK doxygen does not support the documentation of XML files.

The easiest thing I can think of is to write an additional documentation file as described in the question / answer How to add custom files to Doxygen and How to create a 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 appear on the Related Pages tab of your generated documentation. The file will look something like this (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.

In addition, other tools can do what you want. See, for example, this question: Is it possible to document XML using Doxygen, Sandcastle, or other documentation generators?

Answer 2

I have a solution

I found it necessary to document my XML configuration files, and since I use Doxygen for all my other code, I want to use Doxygen. The problem is that Doxygen does not support XML as a source code language (e.g. C ++, Python, etc.). Actually, the problem is worse than Doxygen trying to interpret XML, so hiding Doxygen tags in XML comments is not very good (Doxygen ignores anything in XML comments).

Purpose: XML config file (config.xml) with doxygen tags. Tags must be in an XML file.

Decision:

• XML document file (config.xml)
• Create a Doxygen-compatible document from the XML file (config.xml.md)
• Configure Doxygen to process a document that supports Doxygen (config.xml.md)

Here is the 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 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 assignment of FILE_PATTERNS to your Doxyfile.

 FILE_PATTERNS += *.xml.md 

This XML example will generate a page called “RM6x32 Configuration File” in the “Related Pages” section of the Doxygen documentation.

I hope this helps, and I hope this encourages someone to create a more integrated solution.