Documentazione generata automaticamente per il codice MQL5

1. Introduzione

La maggior parte dei programmatori Java avrà familiarità con la documentazione generata automaticamente che può essere creata con JavaDocs. L'idea è di aggiungere commenti al codice in modo semi-strutturato e che possano poi essere estratti in un file di supporto di facile navigazione.

Il mondo C++ ha anche una serie di generatori automatici di documentazione, con SandCastle e Doxygen di Microsoft, i due leader. Ho deciso di vedere quanto bene Doxygen potesse documentare MQL5, che è in sostanza un sottoinsieme personalizzato di C++. Per me questo è un passo importante nella maturità di MQL5, perché la complessità del linguaggio è facilmente in grado di favorire alcune librerie di classi piuttosto grandi.

L'esperimento ha funzionato molto bene e credo che la documentazione di supporto che Doxygen produce dal codice MQL5 aggiungerà molto valore.

2. Doxygen

Doxygen è un generatore automatico di documentazione open source, disponibile sotto la GNU General Public License, il che significa che il suo sviluppo è stato simile ad altri progetti open source come Linux e Mozilla. Doxygen può essere scaricato e utilizzato gratuitamente, il suo codice sorgente può essere visualizzato da chiunque ed è stato sviluppato e viene migliorato come collaborazione tra un numero di sviluppatori che donano il loro tempo.

Al suo livello di utilizzo più elementare, Doxygen analizza semplicemente tutto il codice C++ (o MQL5) in un progetto e visualizza la sua struttura in un file di aiuto di facile navigazione. Ciò è particolarmente utile con i set di codici orientati agli oggetti, i quali tendono ad avere un'ampia gerarchia di classi e un gran numero di funzioni membro. Per un utilizzo completo delle funzionalità di Doxygen, nel codice dovrebbero essere scritti anche commenti strutturati in modo che Doxygen possa leggerli e aggiungere informazioni nel file di aiuto generato.

2.1 Scaricare Doxygen

La homepage di Doxygen è http://www.doxygen.org/. Da lì puoi accedere alla pagina di download e scaricare l'ultima versione per Windows. Nel momento in cui scriviamo la versione era la doxygen-1.6.1, vedi sotto

Figura 1. Download di Doxygen

2.2 Configurazione ed esecuzione di Doxygen

C'è poco da fare, tranne aggiungere i tipi di file *.mqh e *.mq5 e attivare la generazione del supporto HTML. Le seguenti cinque cifre attraversano la configurazione.

Le prime quattro schermate (figure da 2 a 5) scorrono attraverso le schermate della procedura guidata:

Figura 2. Configurazione di Doxygen - Procedura guidata 1

Figura 3. Configurazione di Doxygen - Procedura guidata 2

Figura 4. Configurazione di Doxygen - Procedura guidata 3

Figura 5. Configurazione di Doxygen - Procedura guidata 4

Infine, c'è una modifica si livello esperto per aggiungere i tipi di file mqh e mq5:

Figura 6. Configurazione di Doxygen - inclusi i file mqh e mq5

E ora è pronto per l'esecuzione. Da notare che Doxgyen memorizzerà e leggerà un file di configurazione e questo è incluso nell'allegato zip a questo articolo.

Figura 7. Avviare Doxygen

2.3 Utilizzo di Doxygen

Doxygen ha un eccellente file di aiuto html compilato (costruito, ovviamente, con Doxygen - ecco la versione html originale) che descrive in dettaglio una straordinaria gamma di funzionalità di documentazione, inclusa la visualizzazione perfetta di complesse formule matematiche. Tuttavia lo strumento può anche essere utilizzato efficacemente in modo molto semplice per creare utili file di supporto.

Ecco un esempio della funzione CiMACD::Create() in MQL5/Include/Oscilators.mqh. Da notare che questi file Indicator non facevano originariamente parte della prima distribuzione beta e potresti dover scaricare nuovamente MetaTtrader 5 per vederli.

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

Alcune semplici modifiche alle parole chiave preparano i commenti all'interpretazione di Doxygen. I commenti ora sono a tripla barra (///), INPUT: è stato modificato in \param e OUTPUT: in \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)

E poi, quando Doxygen lo ha elaborato, il file di supporto appare come nella Figura 8:

Figura 8. CiMACD::Create() come visto nell'HTML generato da Doxygen

2.4 Utilizzo di Doxygen sull'intero codeset MQL5 distribuito

Doxygen è più potente nella creazione di file di supporto per progetti di grandi dimensioni. Distribuiti con MetaTrader 5 nella cartella MQL5 ci sono oltre cento file .mq5 e .mqh, molti dei quali sono correlati.

Ho scritto uno script di utilità MetaquotesCommentsToDoxygen.mq5 (incluso nel file zip allegato) che esegue le conversioni di base dei commenti da Metaquotes a Doxygen descritti sopra. Questo non è un passaggio essenziale per produrre un file di supporto, ma fornisce una dimostrazione delle funzionalità utili di documentazione aggiuntiva di Doxygen.

La procedura che ho usato per produrre un file di supporto del codeset MQL5 è la seguente

• Copia la cartella e le sottocartelle MQL5 in MQL5/files
• Rimuovi MQL5/files/MQL5/Include/Strings/string.mqh - per un motivo sconosciuto questo file ha impedito a Doxygen di completare l'analisi del codice

Facoltativo per documentazione aggiuntiva dai commenti strutturati:

• Dalla cartella MQL5/Files, eseguire il comando Windows/DOS xcopy *.mq* c:\ /S/L > MQL5codeList.txt
• Esegui lo script MetaquotesCommentsToDoxygen.mq5 su qualsiasi grafico

La documentazione di supporto risultante è di buona qualità e dimostra rapidamente la sua utilità - Le figure da 9 a 12 sono un esempio di ciò che puoi vedere

Figura 9. Elenco delle classi generate da Doxygen

Figura 10. Diagramma ad albero delle classi generato da Doxygen per CARrayObj

Figura 11. Elenco delle funzioni membro generate da Doxygen per CARrayObj

Figura 12. Elenco delle definizioni generate dal Doxygen

3. Workshop di assistenza HTML di Microsoft

È necessario un ulteriore passaggio per rendere ancora più utile l'output di Doxygen. Doxygen produce un file index.html che punta a un gran numero di altri file e immagini html. È essenzialmente un piccolo sito ed è quindi molto ingombrante da distribuire.

Molto tempo fa, Microsoft ha riconosciuto che i file di aiuto per le applicazioni Windows dovevano essere scritti in html, quindi hanno sviluppato il loro HTML Help Workshop a questo scopo. L'HTML Help Workshop prende un set di file di aiuto come l'output di Doxygen e lo compila tutto in un singolo file .chm. Questo è lo stesso formato dei file di supporto distribuiti con MetaTrader 5.

3.1 Scaricare HTML Help Workshop

Puoi scaricare e installare htmlhelp.exe dalla pagina Microsoft qui.

Figura 13. Download del supporto HTML

3.2 Creare un file di supporto HTML compilato

L'output dell'elaborazione Doxygen può essere facilmente convertito da HTML Help Workshop in un file di supporto html compilato. Come configurato per questo articolo, Doxygen produce un file index.hhp pronto per l'apertura di HTML Help Workshop, come mostrato di seguito nella Figura 14.

Figura 14. Posizione del file index.hhp generato da Doxygen

 Il passaggio successivo è compilare:

Figura 15. Compilazione con HTML Help

... e al termine, il nuovo file index .chm può essere copiato nella cartella MetaTrader 5/Help e rinominato come mostrato di seguito nelle Figure 16 e 17.

Figura 16. posizione index.chm

Figura 17. index.chm copiato nella cartella di supporto e rinominato

4. Sommario

Questo esercizio mi ha convinto a utilizzare Doxygen o un equivalente in futuro per documentare qualsiasi codice MQL5 che voglio che le persone comprendano e utilizzino e spero che altri facciano lo stesso.

Appendice. Descrizione dei file nei file Doxygen allegati.zip

File	Descrizione	Copia a
MQL5 codeset help.chm	File di supporto HTML compilato di tutto il codice distribuito con MetaTrader 5 versione 229, 8 dicembre 2009.	MetaTrader 5/Help
MetaquotesCommentsToDoxygen.mq5	Script che modifica i commenti nel codice MQL5 per consentire a Doxygen di interpretarli	MQL5/Scripts
MQL5codeList.txt	Un elenco di tutti i file MQL5 distribuiti	MQL5/Files
MQL5_Doxygen	File di configurazione Doxygen	MQL5