Auto-Generated Documentation for MQL5 Code

23 November 2009, 17:57
13 390

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 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

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

Attached files | (1933.39 KB)
Last comments | Go to discussion (8)
gordon | 27 Dec 2009 at 06:38

Oh, I see what you mean about the classes. So maybe not really worth using it for MQL4.

Alain Verleyen
Alain Verleyen | 18 May 2013 at 10:45
Very good article, thanks.
paul deauna
paul deauna | 12 Aug 2017 at 12:17
Alain Verleyen:
Very good article, thanks.
Marcin Rutkowski
Marcin Rutkowski | 8 Nov 2019 at 09:19
MetaQuotes Software Corp.:

New article Auto-Generated Documentation for MQL5 Code is published:

Author: Paul

Is anybody able to use it in 2019 (latest version)   ...i followed the article and I'm not able to have class list generated.


Rahul Dhangar
Rahul Dhangar | 12 Dec 2020 at 19:59
Marcin Rutkowski:

Is anybody able to use it in 2019 (latest version)   ...i followed the article and I'm not able to have class list generated.


Were you able to achieve it?

Step on New Rails: Custom Indicators in MQL5 Step on New Rails: Custom Indicators in MQL5
I will not list all of the new possibilities and features of the new terminal and language. They are numerous, and some novelties are worth the discussion in a separate article. Also there is no code here, written with object-oriented programming, it is a too serous topic to be simply mentioned in a context as additional advantages for developers. In this article we will consider the indicators, their structure, drawing, types and their programming details, as compared to MQL4. I hope that this article will be useful both for beginners and experienced developers, maybe some of them will find something new.
Other classes in DoEasy library (part 66): Signals collection class Other classes in DoEasy library (part 66): Signals collection class
In this article, I will create the signal collection class of the Signals service with the functions for managing signals. Besides, I will improve the Depth of Market snapshot object class for displaying the total DOM buy and sell volumes.
Here Comes the New MetaTrader 5 and MQL5 Here Comes the New MetaTrader 5 and MQL5
This is just a brief review of MetaTrader 5. I can't describe all the system's new features for such a short time period - the testing started on 2009.09.09. This is a symbolical date, and I am sure it will be a lucky number. A few days have passed since I got the beta version of the MetaTrader 5 terminal and MQL5. I haven't managed to try all its features, but I am already impressed.
Brute force approach to pattern search (Part IV): Minimal functionality Brute force approach to pattern search (Part IV): Minimal functionality
The article presents an improved brute force version, based on the goals set in the previous article. I will try to cover this topic as broadly as possible using Expert Advisors with settings obtained using this method. A new program version is attached to this article.