Automatisch generierte Dokumentation für den MQL5-Code

1. Einleitung

Die meisten Personen, die Codes in Java anlegen, kennen bestimmt die automatisch generierte Dokumentation, die zusammen mit JavaDocs erstellt werden kann. Hierbei geht es um die Ergänzung des Codes durch Anmerkungen auf semi-strukturierte Weise, die dann in eine leicht zu navigierende Hilfe-Datei extrahiert werden können.

In der C++ Welt gibt es ebenfalls einige automatische Dokumentations-Geenratoren, von denen SandCastle und Doxygen von Microsoft die beiden Spitzenreiter sind. Ich wollte herausfinden, wie gut Doxygen MQL5 dokumentieren kann, im Grunde ein individuell angepasstes Subset von C++. Für mich bedeutet das einen wichtigen Schritt in der Ausgereiftheit von MQL5, da die Komplexität der Sprache leicht in der Lage ist, einige ziemlich umfassende Klassen-Libraries zu unterstützen.

Der Versuch hat prima funktioniert und ich glaube, dass die Hilfs-Dokumentation, die Doxygen aus dem MQL5-Code erzeugt, ganz erheblichen Mehrwert mit sich bringt.

2. Doxygen

Doxygen ist ein automatischer Open Source Dokumentations-Generator, der unter der GNU-Lizenz für freie Dokumentation zur Verfügung steht, was bedeutet, dass seine Entwicklung anderen Open Sourcen Projekten wie z.B. Linux und Mozilla ähnelt. Doxygen kann gratis heruntergeladen und benutzt werden. Sein Quellcode steht jedem zur Verfügung und seine Entwicklung und weitere Verbesserung werden in gemeinschaftlicher Arbeit von einigen Entwicklern gemacht, die ihre Zeit zur Verfügung stellen.

Auf seiner simpelsten Nutzungsebene, zerlegt Doxygen einfach jeden C++ (oder MQL5) Code in einem Projekt und zeigt seine Struktur in einer leicht zu navigierenden Hilfe-Datei an. Dies ist insbesondere bei Objekt-orientierten Codesets hilfreich, die ja meist eine umfassende Klassenhierarchie und eine große Anzahl an Mitgliedfunktionen haben. Um jedoch alle Features von Doxygen auch komplett nutzen zu können, sollte de Code auch mit strukturierten Anmerkungen versehen sein, damit Doxygen diese lesen und in die generierte Hilfe-Datei entsprechende Informationen hinzufügen kann.

2.1 Doxygen herunterladen

Die Doxygen Homepage lautet: http://www.doxygen.org/. Dort gehen Sie einfach zur Download-Seite und laden sich dort die aktuelle Version für Windows herunter. Als dieser Beitrag entstand war das Doxygen-1.6.1, vgl. unten

Abb. 1 Doxygen herunterladen

2.2 Doxygen konfigurieren und laufen lassen

Dazu muss nicht viel gemacht werden, außer *.mqh und *.mq5 Dateitypen hinzufügen und die Erzeugung von HTML Hilfe aktivieren. Die folgenden fünf Abbildungen laufen auf der Konfiguration.

Die ersten vier Screenshots (Abb. 2 - 5) laufen auf den Assistent-Bildschirmen:

Abb. 2 Doxygen konfigurieren - Assistent 1

Abb. 3 Doxygen konfigurieren - Assistent 2

Abb. 4 Doxygen konfigurieren - Assistent 3

Abb. 5 Doxygen konfigurieren - Assistent 4

Am Schluss kommt ein Wechsel auf ein Experten-Level, um die mqh und mq5 Dateitypen hinzuzufügen:

Abb. 6 Doxygen konfigurieren - einschl. mqh und mq5 Dateien

Fertig. Doxygen läuft jetzt Bitte beachten Sie, dass Doxygen in einer Konfigurationsdatei ablegen und lesen wird, die im zip-Anhang am Ende dieses Beitrags mit eingeschlossen ist.

Abb. 7 Doxygen laufen lassen

2.3 Mit Doxygen arbeiten

Doxygen besitzt eine ausgezeichnete, kompilierte html Hilfe-Datei (natürlich mit Doxygen aufgebaut - dies ist die Originalversion in HTML), die ein erstaunliche Menge an Dokumentations-Features detailliert aufführt, einschl. der perfekten Anzeige von komplexen math. Formeln. Dieses Tool kann jedoch auch auf einfache Weise ganz effektiv zum Anlegen nützlicher Hilfe-Dateien verwendet werden.

Hier ist ein Beispiel der CiMACD::Create() Funktion in MQL5/Include/Oscilators.mqh. Bitte beachten Sie: diese Indikatordateien gehörten ursprünglich nicht zur ersten, verteilten Betaversion, daher müssen Sie u.U. MetaTrader 5 noch einmal herunterladen, um sie zu sehen.

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

Mit Hilfe einiger kleinen Änderungen an den Schlüsselwörtern werden die Anmerkungen zur Interpretation durch Doxygen vorbereitet. Die Anmerkungen sind jetzt durch einen dreifachen Slash (///) gekennzeichnet, INPUT: wurde verändert zu \param, und OUTPUT: zu \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)

Wenn Doxygen sie dann verarbeitet hat, sieht die Hilfe-Datei so aus wie in Abb. 8:

Abb. 8 CiMACD::Create() wie sie im Doxygen-generierten HTML angezeigt wird

2.4 Doxygen auf dem gesamten, verteilten MQL5 Codeset anwenden

Die absolute Stärke von Doxygen liegt in seiner Erzeugung einer Hilfe-Datei für Großprojekte. Mit dem MetaTrader 5 werden im MQL5-Ordner mehr als 100 .mq5 und .mqh Dateien verteilt, von denen viele miteinander zusammenhängen.

Ich habe ein Dienstscript, MetaquotesCommentsToDoxygen.mq5, geschrieben (ebenfalls in der am Schluss angehängten zip-Datei vorhanden), das die grundlegenden Umwandlungen von Metaquotes- in Doxygen-Anmerkungen, wie zuvor beschrieben, ausführt. Dies ist zwar für die Erzeugung einer Hilfe-Datei nicht zwingend notwendig, liefert aber dennoch einen Beweis der sinnvollen, zusätzlichen Dokumentations-Features von Doxygen.

Zue Erzeugung einer MQL5-Codeset Hilfe-Datei bin ich folgendermaßen vorgegangen:

• Den MQL5-Ordner samt Unterordner in die MQL5/Dateien kopieren
• MQL5/files/MQL5/Include/Strings/string.mqh entfernen - aus einem mir nicht bekannten Grund, hinderte diese Datei Doxygen daran, die Zerteilung des Codes komplett abzuschließen

Optional für zusätzliche Dokumentation von strukturierten Anmerkungen:

• Aus dem MQL5/Files Ordner dann den folgenden Windows/DOS Befehl ablaufen lassen: xcopy *.mq* c:\ /S/L > MQL5codeList.txt
• Das MetaquotesCommentsToDoxygen.mq5 Script auf jedem Chart ausführen

Die so entstandenen Hilfsdokumentation ist von guter Qualität und beweist schnell ihre Nützlichkeit: Abbildungen 9 - 12 zeigen Ihnen, was Sie dann sehen können

Abb. 9 Von Doxygen generierte 'Klassen' Liste

Abb. 10 Von Doxygen generiertes 'Klassen-Baumdiagramm' für CArrayObj

Abb. 11 Von Doxygen generierte 'Mitglieder-Funktionsliste' für CArrayObj

Abb. 12 Von Doxygen generierte 'Defines'-Liste

3. Der Microsoft HTML Help Workshop

Damit das Ergebnis von Doxygen noch sinnvoller und nützlicher wird, muss man noch einen weiteren Schritt einhalten. Doxygen erzeugt eine index.html Datei, die auf eine große Anzahl an anderen html-Dateien und Bildern verweist. Im Grunde handelt es sich hier um eine kleine Website, die deswegen ziemlich umständlich zu verteilen ist.

Microsoft hat schon seit langem erkannt, dass Hilfe-Dateien für Windows-Anwendungen in html geschrieben werden müssen und hat deshalb seinen HTML Help Workshop entwickelt. Der HTML Help Workshop nimmt ein Hilfe-FileSet, wie eben das Ergebnis von Doxygen, und kompiliert es in eine einzige single .chm Datei. Und zwar im gleichen Format wie die mit MetaTrader 5 verteilten Hilfe-Dateien.

3.1 HTML Help Workshop herunterladen

Sie können htmlhelp.exe von der Microsoft-Seite hier herunterladen und installieren.

Abb. 13 HTML Help herunterladen

3.2 Eine kompilierte HTML Hilfe-Datei erstellen

Das Ergebnis der Verarbeitung durch Doxygen kann mit Hilfe des HTML Hilfe-Workshops leicht in eine kompilierte html Hilfe-Datei umgewandelt werden. Wie für diesen Beitrag konfiguriert, liefert Doxygen eine index.hhp-Datei, die vom HTML Help Workshop sofort geöffnet werden kann. Vgl. dazu Abb. 14.

Abb. 14 Standort der von Doxygen generierten index.hhp Datei

 Als nächster Schritt folgt die Kompilierung:

Abb. 15. Kompilieren mit HTML Help

Ist dies geschehen, kann die neue index.chm Datei in den MetaTrader 5/Hilfe-Ordner kopiert und umbenannt werden, so wie in Abb. 16 und 17 gezeigt.

Abb. 16 index.chm Standort

Abb. 17 index.chm, in den Hilfe-Ordner kopiert und umbenannt

4. Zusammenfassung

Diese Übung hat mich davon überzeugt, auch in Zukunft Doxygen oder etwas Ähnliches zur Dokumentation jedes MQL5-Codes zu benutzen, von dem ich möchte, dass Menschen ihn verstehen und verwenden. Ich hoffe, dass es anderen genauso geht wie mir.

Anhang. Beschreibung der in der angehängten Doxygen-Dateien.zip-Datei enthaltenen Dateien

Datei	Beschreibung	Kopiere nach
MQL5 codeset help.chm	Kompilierte HTML Hilfe-Datei des gesamten, mit MetaTrader 5, Bauart 229, am 8. Dezember 2009, verteilten Codes.	MetaTrader 5/Help
MetaquotesCommentsToDoxygen.mq5	Script zur Modifizierung von Anmerkungen im MQL5-Code, damit sie von Doxygen interpretiert werden können	MQL5/Scripts
MQL5codeList.txt	Liste aller verteilten MQL5-Dateien	MQL5/Dateien
MQL5_Doxygen	Doxygen Konfigurationsdatei	MQL5