Download MetaTrader 5

Auto-Generated Documentation for MQL5 Code

23 November 2009, 17:57
Paul
5
4 799

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

Attached files |
doxygen_files.zip (1933.39 KB)
Last comments | Go to discussion (5)
Philipp
Philipp | 22 Dec 2009 at 18:02

Great article!

gordon
gordon | 26 Dec 2009 at 02:18
Can I use it with MQL4? It is very much like C after all, and doxygen is supposed to support that too.

Paul
Paul | 27 Dec 2009 at 02:48
gordon   :
Can I use it with MQL4? It is very much like C after all, and doxygen is supposed to support that too.

Yes, it works gordon.  There's an option in the second Wizard Mode screen to "optimize for C or PHP output".  Obviously all MQL4 functions are global, so there are no advantages of the MQL5 class grouping.

 

I've attached a screenshot below of some output for LibOrderReliable using the C option.  LibOrderReliable is a very well documented wrapper for the MQL4 trade functions to make them more fail-safe.  To have the documentation appear in the Doxygen output, the in-code comments would need similar adjustments to the ones I did on the MQL5 code.

 

Paul

http://paulsfxrandomwalk.blogspot.com/ 

 

 

 

 

 

gordon
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.
False trigger protection for Trading Robot False trigger protection for Trading Robot

Profitability of trading systems is defined not only by logic and precision of analyzing the financial instrument dynamics, but also by the quality of the performance algorithm of this logic. False trigger is typical for low quality performance of the main logic of a trading robot. Ways of solving the specified problem are considered in this article.

Using text files for storing input parameters of Expert Advisors, indicators and scripts Using text files for storing input parameters of Expert Advisors, indicators and scripts

The article describes the application of text files for storing dynamic objects, arrays and other variables used as properties of Expert Advisors, indicators and scripts. The files serve as a convenient addition to the functionality of standard tools offered by MQL languages.