Auto-Generated Documentation for MQL5 Code

1. Introduction

Most Java coders will be familiar with the auto-generated documentation that can be created with JavaDocs. The idea is to add comments into the code in a semi-structured way that can then be extracted into an easy to navigate help file.

The C++ world also has a number of documentation auto-generators, with Microsoft's SandCastle and Doxygen being two leaders. I decided to see how well Doxygen could document MQL5, which is in essence a customised subset of C++. To me this is an important step in the maturity of MQL5, because the complexity of the language is easily capable of fostering some quite large class libraries.

The experiment worked very well and I believe the help documentation that Doxygen produces from MQL5 code will add a great deal of value.

2. Doxygen

Doxygen is an open source automatic documentation generator available under the GNU General Public License, which means that its development has been similar to other open source projects such as Linux and Mozilla. Doxygen is free to download and use, its source code is open for anyone to view, and it has been developed and is being enhanced as a collaboration between an number of developers who donate their time.

At its most basic level of usage, Doxygen simply parses all the C++ (or MQL5) code in a project and displays its structure in an easy to navigate help file. This is particularly useful with Object Oriented codesets, which tend to have an extensive class hierachy and a large number of member functions. For full use of the Doxygen features, structured comments should also be written into the code so that Doxygen can read them and add information into the generated help file.

2.1 Downloading Doxygen

The Doxygen homepage is http://www.doxygen.org/. From there you can navigate to the download page and download the latest version for Windows. At time of writing this was doxygen-1.6.1, see below

Figure 1. Doxygen download

2.2 Configuring and running Doxygen

Little needs to be done, except to add *.mqh and *.mq5 filetypes and switch on the generation of HTML help. The following five figures run through the configuration.

The first four screenshots (Figures 2 to 5) run through the Wizard screens:

Figure 2. Configuring Doxygen - Wizard 1

Figure 3. Configuring Doxygen - Wizard 2

Figure 4. Configuring Doxygen - Wizard 3

Figure 5. Configuring Doxygen - Wizard 4

Finally, there is one expert level change, to add the mqh and mq5 filetypes:

Figure 6. Configuring Doxygen - including mqh and mq5 files

And now, it's ready to run. Note that Doxgyen will store and read in a configuration file and this is included in the zip attachement to this article.

Figure 7. Running Doxygen

2.3 Using Doxygen

Doxygen has an excellent compiled html help file (constructed, of course, with Doxygen - here's the original html version) which details an amazing array of documentation features including the perfect display of complex mathematical formulae. However the tool can also be used effectively in a very simple way to create useful help files.

Here's an example of the CiMACD::Create() function in MQL5/Include/Oscilators.mqh. Note that these Indicator files were not originally part of the early beta distribution and you may need to re-download MetaTtrader 5 to see them.

//+------------------------------------------------------------------+
//| Create indicator "Moving Averages Convergence-Divergence".       |
//| INPUT:  symbol          -chart symbol,                           |
//|         period          -chart period,                           |
//|         fast_ema_period -period fast EMA,                        |
//|         slow_ema_period -period slow EMA,                        |
//|         signal_period   -period signal MA,                       |
//|         applied         -what used.                              |
//| OUTPUT: true-if successful, false otherwise.                     |
//| REMARK: no.                                                      |
//+------------------------------------------------------------------+
bool CiMACD::Create(string symbol,
                    ENUM_TIMEFRAMES period,
                    int fast_ema_period,
                    int slow_ema_period,
                    int signal_period,
                    int applied)

Some simple changes to the keywords prepare the comments for interpretation by Doxygen. The comments are now triple-slash (///), INPUT: has been changed to \param, and OUTPUT: to \return

//+------------------------------------------------------------------+
/// Create indicator "Moving Averages Convergence-Divergence".        
/// \param  symbol          -chart symbol,                            
/// \param  period          -chart period,                            
/// \param  fast_ema_period -period fast EMA,                         
/// \param  slow_ema_period -period slow EMA,                         
/// \param  signal_period   -period signal MA,                        
/// \param  applied         -what used.                               
/// \return true-if successful, false otherwise.                      
//+------------------------------------------------------------------+
bool CiMACD::Create(string symbol,
                    ENUM_TIMEFRAMES period,
                    int fast_ema_period,
                    int slow_ema_period,
                    int signal_period,
                    int applied)

And then when Doxygen has processed it, the help file looks like Figure 8:

Figure 8. CiMACD::Create() as seen in Doxygen-generated HTML

2.4 Using Doxygen on the entire distributed MQL5 codeset

Where Doxygen is at its most powerful is in creating a help file for large projects. Distributed with MetaTrader 5 under the MQL5 folder are over one hundred .mq5 and .mqh files, many of which are interrelated.

I wrote a utility script MetaquotesCommentsToDoxygen.mq5 (included in the attached zip file) which performs the basic Metaquotes to Doxygen comment conversions outlined above. This is not an essential step to produce a help file, but it provides a demonstration of the useful additional documentation features of Doxygen.

The procedure I used to produce an MQL5 codeset help file is as follows

• Copy the MQL5 folder and subfolders into MQL5/files
• Remove MQL5/files/MQL5/Include/Strings/string.mqh - for an unknown reason this file prevented Doxygen from completing its code parse

Optional for additional documentation from structured comments:

• From the MQL5/Files folder, run the Windows/DOS command xcopy *.mq* c:\ /S/L > MQL5codeList.txt
• Execute the MetaquotesCommentsToDoxygen.mq5 script on any chart

The resulting help documentation is good quality and quickly demonstrates its usefulness - Figures 9 to 12 are a sample of what you can see

Figure 9. Doxygen-generated Class list

Figure 10. Doxygen-generated Class tree diagram for CArrayObj

Figure 11. Doxygen-generated member functions list for CArrayObj

Figure 12. Doxygen-generated Defines list

3. Microsoft's HTML Help Workshop

There is one further step needed to make the output from Doxygen even more useful. Doxygen produces an index.html file which points to a large number of other html files and pictures. It's essentially a small website, and is therefore very cumbersome to distribute.

Long ago, Microsoft recognised that help files for Windows applications should be written in html, so they developed their HTML Help Workshop for this purpose. The HTML Help Workshop takes a help fileset such as the output from Doxygen and compiles it all into a single .chm file. This is the same format as the help files distributed with MetaTrader 5.

3.1 Downloading HTML Help Workshop

You can download and install htmlhelp.exe from the Microsoft page here.

Figure 13. Downloading HTML Help

3.2 Making a compiled HTML help file

The output from Doxygen processing can easily be converted by HTML Help Workshop into a compiled html help file. As configured for this article, Doxygen produces an index.hhp file ready for HTML Help Workshop to open, as shown below in Figure 14.

Figure 14. Location of the index.hhp file generated by Doxygen

 The next step is to compile:

Figure 15. Compiling with HTML Help

... and when it's finished, the new index .chm file can be copied into the MetaTrader 5/Help folder and renamed, as shown below in Figure 16 and 17.

Figure 16. index.chm location

Figure 17. index.chm copied into the help folder and renamed

4. Summary

This exercise has convinced me to use Doxygen or an equivalent in future to document any MQL5 code that I want people to understand and use, and I hope others do likewise.

Appendix. Description of the files in the attached Doxygen files.zip

File	Description	Copy to
MQL5 codeset help.chm	Compiled HTML help file of all code distributed with MetaTrader 5 build 229, 8th December 2009.	MetaTrader 5/Help
MetaquotesCommentsToDoxygen.mq5	Script which modifies comments in MQL5 code to enable Doxygen to interpret them	MQL5/Scripts
MQL5codeList.txt	A list of all distributed MQL5 files	MQL5/Files
MQL5_Doxygen	Doxygen configuration file	MQL5