Documentation générée automatiquement pour le code MQL5

Paul | 12 janvier, 2022

1. Introduction

La plupart des codeurs Java connaissent la documentation générée automatiquement qui peut être créée avec JavaDocs. L'idée est d'ajouter des commentaires dans le code de manière semi-structurée qui peuvent ensuite être extraits dans un fichier d'aide facile à naviguer.

Le monde du C++ dispose également d'un certain nombre de générateurs automatiques de documentation, SandCastle de Microsoft et Doxygen étant les deux principaux. J'ai décidé de voir dans quelle mesure Doxygen pouvait documenter MQL5, qui est essentiellement un sous-ensemble personnalisé de C++. Pour moi, il s'agit d'une étape importante dans la maturité de MQL5, car la complexité du langage permet de créer des librairies de classes assez importantes.

L'expérience a très bien fonctionné et je pense que la documentation d'aide que Doxygen produit à partir du code MQL5 apportera une grande valeur ajoutée.

2. Doxygen

Doxygen est un générateur de documentation automatique open source disponible sous la licence publique générale GNU, ce qui signifie que son développement a été similaire à d'autres projets open source tels que Linux et Mozilla. Doxygen peut être téléchargé et utilisé gratuitement, son code source est accessible à tous et il a été développé et est en cours d'amélioration grâce à la collaboration d'un certain nombre de développeurs qui donnent de leur temps.

À son niveau d'utilisation le plus basique, Doxygen analyse simplement tout le code C++ (ou MQL5) d'un projet et affiche sa structure dans un fichier d'aide facile à consulter. Ceci est particulièrement utile avec les jeux de codes orientés objet, qui ont tendance à avoir une hiérarchie de classes étendue et un grand nombre de fonctions membres. Pour utiliser pleinement les fonctionnalités de Doxygen, des commentaires structurés doivent également être écrits dans le code afin que Doxygen puisse les lire et ajouter des informations dans le fichier d'aide généré.

2.1 Télécharger Doxygen

La page d'accueil de Doxygen est http://www.doxygen.org/. De là, vous pouvez naviguer vers la page de téléchargement et télécharger la dernière version pour Windows. Au moment de la rédaction, il s'agissait de doxygen-1.6.1, voir ci-dessous

Figure 1. Télécharger Doxygen

2.2 Configurer et exécuter Doxygen

Il n'y a pas grand-chose à faire, si ce n'est d'ajouter les types de fichiers *.mqh et *.mq5 et d'activer la génération de l'aide HTML. Les cinq figures suivantes présentent la configuration.

Les quatre premières captures d'écran (figures 2 à 5) présentent les écrans de l'assistant :

Figure 2. Configuration de Doxygen - Assistant 1

Figure 3. Configuration de Doxygen - Assistant 2

Figure 4. Configuration de Doxygen - Assistant 3

Figure 5. Configuration de Doxygen - Assistant 4

Enfin, il y a un changement de niveau expert, pour ajouter les types de fichiers mqh et mq5 :

Figure 6. Configuration de Doxygen - y compris les fichiers mqh et mq5

Et maintenant, c'est prêt à fonctionner. Notez que Doxgyen va stocker et lire dans un fichier de configuration, qui est inclus dans le fichier zip joint à cet article.

Figure 7. Exécution de Doxygen

2.3 Utiliser Doxygen

Doxygen dispose d'un excellent fichier d'aide compilé en html (construit, bien sûr, avec Doxygen - voici la version originale en html) qui détaille une gamme étonnante de fonctionnalités de documentation, y compris l'affichage parfait de formules mathématiques complexes. Cependant, l'outil peut également être utilisé efficacement d'une manière très simple pour créer des fichiers d'aide utiles.

Voici un exemple de la fonction CiMACD::Create() dans MQL5/Include/Oscilators.mqh. Notez que ces fichiers d'indicateurs ne faisaient pas partie à l'origine de la distribution de la version bêta et que vous devrez peut-être retélécharger MetaTtrader 5 pour les voir.

//+------------------------------------------------------------------+
//| 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)

Quelques modifications simples des mots-clés préparent les commentaires à une interprétation par Doxygen. Les commentaires sont désormais en triple barre oblique (///), INPUT : a été remplacé par \param, et OUTPUT : par \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)

Et lorsque Doxygen l'a traité, le fichier d'aide ressemble à la Figure 8 :

Figure 8. CiMACD::Create() vu dans le HTML généré par Doxygen

2.4 Utilisation de Doxygen sur l'ensemble du jeu de codes MQL5 distribué

C'est dans la création d'un fichier d'aide pour les grands projets que Doxygen est le plus puissant. Plus d'une centaine de fichiers .mq5 et .mqh, dont beaucoup sont interdépendants, sont distribués avec MetaTrader 5 dans le dossier MQL5.

J'ai écrit un script utilitaire MetaquotesCommentsToDoxygen.mq5 (inclus dans le fichier zip ci-joint) qui effectue les conversions de base des commentaires Metaquotes vers Doxygen décrites ci-dessus. Il ne s'agit pas d'une étape essentielle pour produire un fichier d'aide, mais elle permet de démontrer l'utilité des fonctions de documentation supplémentaires de Doxygen.

La procédure que j'ai utilisée pour produire un fichier d'aide MQL5 codeset est la suivante

• Copier le dossier et les sous-dossiers de MQL5 dans MQL5/files
• Supprimer MQL5/files/MQL5/Include/Strings/string.mqh - pour une raison inconnue, ce fichier a empêché Doxygen de terminer son analyse de code

Facultatif pour la documentation supplémentaire à partir de commentaires structurés :

• À partir du dossier MQL5/Files, exécutez la commande Windows/DOS xcopy *.mq* c:\ /S/L > MQL5codeList.txt
• Exécutez le script MetaquotesCommentsToDoxygen.mq5 sur n'importe quel graphique

La documentation d'aide qui en résulte est de bonne qualité et démontre rapidement son utilité - Les figures 9 à 12 sont un exemple de ce que vous pouvez voir

Figure 9. Liste de classe générée par Doxygen

Figure 10. Diagramme d'arborescence de classes généré par Doxygen pour CArrayObj

Figure 11. Liste des fonctions membres générées par Doxygen pour CArrayObj

Figure 12. Liste de définitions générée par Doxygen

3. Atelier d'aide HTML de Microsoft

Une étape supplémentaire est nécessaire pour rendre les résultats de Doxygen encore plus utiles. Doxygen produit un fichier index.html qui pointe vers un grand nombre d'autres fichiers et images html. Il s'agit essentiellement d'un petit site Web, et il est donc très lourd à distribuer.

Il y a longtemps, Microsoft a reconnu que les fichiers d'aide pour les applications Windows devaient être écrits en html, c'est pourquoi ils ont développé leur atelier d'aide HTML à cet effet. L'atelier d'aide HTML prend un ensemble de fichiers d'aide tel que la sortie de Doxygen et le compile dans un seul fichier .chm. C'est le même format que les fichiers d'aide distribués avec MetaTrader 5.

3.1 Téléchargement de l'atelier d'aide HTML

Vous pouvez télécharger et installer htmlhelp.exe depuis la page de Microsoft ici.

Figure 13. Téléchargement de l'aide HTML

3.2 Créer un fichier d'aide HTML compilé

Le résultat du traitement Doxygen peut facilement être converti par HTML Help Workshop en un fichier d'aide html compilé. Tel que configuré pour cet article, Doxygen produit un fichier index.hhp prêt à être ouvert par le HTML Help Workshop, comme le montre la figure 14 ci-dessous.

Figure 14. Emplacement du fichier index.hhp généré par Doxygen

 L'étape suivante consiste à compiler :

Figure 15. Compilation avec l'aide HTML

... et une fois terminé, le nouveau fichier d'index .chm peut être copié dans le dossier MetaTrader 5/Help et renommé, comme illustré ci-dessous dans les figures 16 et 17.

Figure 16. Emplacement du fichier index.chm

Figure 17. index.chm copié dans le dossier d'aide et renommé

4. Sommaire

Cet exercice m'a convaincu d'utiliser Doxygen ou un équivalent à l'avenir pour documenter tout code MQL5 que je souhaite que les gens comprennent et utilisent, et j'espère que d'autres feront de même.

Annexe. Description des fichiers dans le fichier joint Doxygen files.zip