MQL5 Kodu için Otomatik Oluşturulan Belgeler

1. Giriş

Çoğu Java kodlayıcısı, JavaDocs ile oluşturulabilen otomatik olarak oluşturulmuş belgelere aşinadır. Buradaki fikir, koda daha sonra gezinmesi kolay bir yardım dosyasına çıkarılabilecek yarı yapılandırılmış bir şekilde açıklamalar eklemektir.

C++ dünyası ayrıca Microsoft SandCastle ve Doxygen'in iki lider olduğu bir dizi otomatik belge oluşturucu içerir. Doxygen'in esas itibariyle C++'nın özelleştirilmiş bir alt kümesi olan MQL5'i ne kadar iyi belgeleyebileceğini görmeye karar verdim. Bence bu, MQL5'in olgunlaşmasında önemli bir adım; zira dilin karmaşıklığı oldukça büyük sınıf kitaplıklarının bazılarını kolaylıkla besleyebilir.

Deneme çok iyi çalıştı ve Doxygen'in MQL5 kodundan ürettiği yardım belgelerinin büyük bir değer katacağına inanıyorum.

2. Doxygen

Doxygen, GNU Genel Kamu Lisansı altında bulunan açık kaynaklı bir otomatik belgeleme oluşturucusudur; bu, gelişiminin Linux ve Mozilla gibi diğer açık kaynaklı projelere benzer olduğu anlamına gelir. Doxygen'i indirmek ve kullanmak ücretsizdir ve kaynak kodunu herkes görüntüleyebilir; Doxygen, bu işe zaman ayıran birkaç geliştiricinin işbirliğiyle geliştirildi ve halihazırda geliştirilmeye devam etmektedir.

En temel kullanım düzeyinde, Doxygen bir projedeki tüm C++ (veya MQL5) kodunu basitçe ayrıştırır ve yapısını gezinmesi kolay bir yardım dosyasında görüntüler. Bu, özellikle kapsamlı bir sınıf hiyerarşisine ve çok sayıda üye işleve sahip olma eğiliminde olan Nesne Yönelimli kod kümeleri için kullanışlıdır. Doxygen özelliklerinin tam olarak kullanılması için, Doxygen'in bunları okuyabilmesi ve oluşturulan yardım dosyasına bilgi ekleyebilmesi için aynı zamanda yapılandırılmış açıklamaların da koda yazılması gerekir.

2.1 Doxygen'i İndirme

Doxygen ana sayfasına şuradan ulaşabilirsiniz: http://www.doxygen.org/. Buradan indirme sayfasına gidebilir ve Windows için en son sürümü indirebilirsiniz. Yazma sırasında bu, doxygen-1.6.1 idi, aşağıya bakınız.

Şekil 1. Doxygen'i indirme

2.2 Doxygen'i yapılandırma ve çalıştırma

*.mqh ve *.mq5 dosya türlerini eklemek ve HTML yardımı oluşturmayı açmak dışında yapılması gereken çok az şey vardır. Aşağıdaki beş şekil yapılandırmadan geçer.

İlk dört ekran görüntüsü (Şekil 2 ila 5) Sihirbaz ekranlarından geçer:

Şekil 2. Doxygen'i Yapılandırma - Sihirbaz 1

Şekil 3. Doxygen'i Yapılandırma - Sihirbaz 2

Şekil 4. Doxygen'i Yapılandırma - Sihirbaz 3

Şekil 5. Doxygen'i Yapılandırma - Sihirbaz 4

Son olarak, mqh ve mq5 dosya türlerini eklemek için expert düzeyinde bir değişiklik vardır:

Şekil 6. Doxygen'i yapılandırma - mqh ve mq5 dosyaları dahil

Ve şimdi, çalışmaya hazır. Doxgyen'in bir yapılandırma dosyasında depolayıp okuyacağını ve bunun bu makalenin zip ekinde bulunduğunu unutmayın.

Şekil 7. Doxygen'i Çalıştırma

2.3 Doxygen'in Kullanımı

Doxygen karmaşık matematiksel formüllerin mükemmel görüntüsü de dahil olmak üzere muhteşem bir belgeleme özellikleri dizisini detaylandıran mükemmel bir derlenmiş html yardım dosyası içerir (elbette Doxygen ile oluşturulmuş - orijinal html sürümü buradadır). Ancak araç, faydalı yardım dosyaları oluşturmak için çok basit bir şekilde etkili olarak kullanılabilir.

MQL5/Include/Oscilators.mqh dosyasındaki CiMACD::Create() işlevine bir örnek. Bu Gösterge dosyalarının orijinal olarak erken beta dağıtımının bir parçası olmadığını ve bunları görmek için MetaTtrader 5'i tekrar indirmeniz gerekebileceğini unutmayın.

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

Anahtar sözcüklerde yapılan bazı basit değişiklikler, açıklamaları Doxygen tarafından yorumlanmak üzere hazırlar. Şimdi açıklamalar üç eğik çizgi (///), GİRİŞ:, \param ve ÇIKIŞ:, \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)

olarak değiştirildi

Ve bunun ardından Doxygen onu işlediğinde, yardım dosyası Şekil 8'deki gibi görünür:

Şekil 8. Doxygen tarafından oluşturulan HTML'de görüldüğü gibi CiMACD::Create()

2.4 Dağıtılmış MQL5 kod kümesinin tamamında Doxygen'i kullanma

Doxygen'in en güçlü olduğu konu, büyük projeler için bir yardım dosyası oluşturmaktır. MetaTrader 5 ile MQL5 klasörü altında dağıtılan, çoğu birbiriyle ilişkili yüzün üzerinde .mq5 ve .mqh dosyasıdır.

Yukarıda özetlenen temel Metaquotes - Doxygen açıklama dönüştürmelerini gerçekleştiren MetaquotesCommentsToDoxygen.mq5 (ekli zip dosyasında yer alır) bir yardımcı script dosyası yazdım. Bu, bir yardım dosyası oluşturmak için gerekli bir adım değildir, ancak Doxygen'in faydalı ek belgeleme özelliklerinin bir gösterimini sağlar.

Bir MQL5 kod kümesi yardım dosyası oluşturmak için kullandığım yordam aşağıdaki gibidir.

• MQL5 klasörünü ve alt klasörlerini MQL5/files içine kopyalayın
• MQL5/files/MQL5/Include/Strings/string.mqh'yi kaldırın - bilinmeyen bir nedenle bu dosya Doxygen'in kod ayrıştırmasını tamamlamasını engelledi

Yapılandırılmış açıklamalardan ek belgeler için isteğe bağlı:

• MQL5/Files klasöründen, Windows/DOS komutunu xcopy *.mq* c:\ /S/L > MQL5codeList.txt çalıştırın
• Herhangi bir grafikte MetaquotesCommentsToDoxygen.mq5 script dosyasını yürütün

Ortaya çıkan yardım belgeleri kalitelidir ve kullanışlılığını hızlı bir şekilde gösterir - Şekil 9 ila 12, gördüklerinize ilişkin örnekler içerir

Şekil 9. Doxygen tarafından oluşturulan Sınıf listesi

Şekil 10. CArrayObj için Doxygen tarafından oluşturulan Sınıf ağacı diyagramı

Şekil 11. CArrayObj için Doxygen tarafından oluşturulan üye işlevleri listesi

Şekil 12. Doxygen tarafından oluşturulan Tanımlar listesi

3. Microsoft'un HTML Yardım Atölyesi

Doxygen'den alınan çıktıyı daha da kullanışlı hale getirmek için gereken bir adım daha vardır. Doxygen, çok sayıda başka html dosyasına ve resme işaret eden bir index.html dosyası oluşturur. Aslında bu, küçük bir web sitesidir ve bu nedenle dağıtılması çok elverişsizdir.

Uzun zaman önce Microsoft, Windows uygulamaları için yardım dosyalarının html ile yazılması gerektiğini fark etti ve bu amaçla HTML Yardım Atölyesini geliştirdiler. HTML Yardım Atölyesi, Doxygen'den çıktı gibi bir yardım dosyası kümesi alır ve tamamını tek bir .chm dosyasında derler. Bu, MetaTrader 5 ile dağıtılan yardım dosyalarıyla aynı biçimdedir.

3.1 HTML Yardım Atölyesini İndirme

htmlhelp.exe dosyasını buradan Microsoft sayfasından indirip yükleyebilirsiniz.

Şekil 13. HTML Yardımını İndirme

3.2 Derlenmiş bir HTML yardım dosyası oluşturma

Doxygen işlemenin çıktısı, HTML Yardım Atölyesi tarafından derlenmiş bir html yardım dosyasına kolaylıkla dönüştürülebilir. Bu makale için yapılandırıldığı üzere Doxygen, aşağıda Şekil 14'te gösterildiği gibi HTML Yardım Atölyesi'nin açması için hazır bir index.hhp dosyası oluşturur.

Şekil 14. Doxygen tarafından oluşturulan index.hhp dosyasının konumu

 Bir sonraki adım derlemedir:

Şekil 15. HTML Yardımı ile Derleme

... ve tamamlandığında, aşağıda Şekil 16 ve 17'de gösterildiği gibi yeni index .chm dosyası MetaTrader 5/Yardım klasörüne kopyalanabilir ve yeniden adlandırılabilir.

Şekil 16. index.chm'nin konumu

Şekil 17. Yardım klasörüne kopyalanan ve yeniden adlandırılan index.chm

4. Özet

Bu alıştırma beni, insanların anlamasını ve kullanmasını istediğim herhangi bir MQL5 kodunu belgelemek için gelecekte Doxygen veya eşdeğerini kullanma konusunda ikna etti ve umarım başkalarını da aynı şekilde ikna eder.

Ek. Ekli Doxygen files.zip dosyasındaki dosyaların açıklaması

Dosya	Açıklama	Kopyalama Hedefi
MQL5 codeset help.chm	MetaTrader 5 yapı 229 ile dağıtılan tüm kodların derlenmiş HTML yardım dosyası, 8 Aralık 2009.	MetaTrader 5/Yardım
MetaquotesCommentsToDoxygen.mq5	Doxygen'in bunları yorumlamasını sağlamak için MQL5 kodundaki açıklamaları değiştiren script dosyası	MQL5/Script Dosyaları
MQL5codeList.txt	Dağıtılan tüm MQL5 dosyalarının listesi	MQL5/Dosyalar
MQL5_Doxygen	Doxygen yapılandırma dosyası	MQL5